net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14
  15 /**
  16  * Common protocol for Java elements that must be opened before they can be
  17  * navigated or modified. Opening a textual element (such as a compilation unit)
  18  * involves opening a buffer on its contents. While open, any changes to the
  19  * buffer can be reflected in the element's structure; see
  20  * <code>isConsistent</code> and <code>makeConsistent(IProgressMonitor)</code>.
  21  * <p>
  22  * To reduce complexity in clients, elements are automatically opened by the
  23  * Java model as element properties are accessed. The Java model maintains an
  24  * LRU cache of open elements, and automatically closes elements as they are
  25  * swapped out of the cache to make room for other elements. Elements with
  26  * unsaved changes are never removed from the cache, and thus, if the client
  27  * maintains many open elements with unsaved changes, the LRU cache can grow in
  28  * size (in this case the cache is not bounded). However, as elements are saved,
  29  * the cache will shrink back to its original bounded size.
  30  * </p>
  31  * <p>
  32  * To open an element, all openable parent elements must be open. The Java model
  33  * automatically opens parent elements, as it automatically opens elements.
  34  * Opening an element may provide access to direct children and other
  35  * descendants, but does not automatically open any descendents which are
  36  * themselves <code>IOpenable</code>. For example, opening a compilation unit
  37  * provides access to all its constituent elements, but opening a package
  38  * fragment does not open all compilation units in the package fragment.
  39  * </p>
  40  * <p>
  41  * This interface is not intended to be implemented by clients.
  42  * </p>
  43  */
  44 public interface IOpenable {
  45
  46         /**
  47          * Closes this element and its buffer (if any). Closing an element which is
  48          * not open has no effect.
  49          *
  50          * <p>
  51          * Note: although <code>close</code> is exposed in the API, clients are
  52          * not expected to open and close elements - the Java model does this
  53          * automatically as elements are accessed.
  54          *
  55          * @exception JavaModelException
  56          *                if an error occurs closing this element
  57          */
  58         public void close() throws JavaModelException;
  59
  60         /**
  61          * Returns the buffer opened for this element, or <code>null</code> if
  62          * this element does not have a buffer.
  63          *
  64          * @exception JavaModelException
  65          *                if this element does not exist or if an exception occurs
  66          *                while accessing its corresponding resource.
  67          * @return the buffer opened for this element, or <code>null</code> if
  68          *         this element does not have a buffer
  69          */
  70         public IBuffer getBuffer() throws JavaModelException;
  71
  72         /**
  73          * Returns <code>true</code> if this element is open and:
  74          * <ul>
  75          * <li>its buffer has unsaved changes, or
  76          * <li>one of its descendants has unsaved changes, or
  77          * <li>a working copy has been created on one of this element's children
  78          * and has not yet destroyed
  79          * </ul>
  80          *
  81          * @exception JavaModelException
  82          *                if this element does not exist or if an exception occurs
  83          *                while accessing its corresponding resource.
  84          * @return <code>true</code> if this element is open and:
  85          *         <ul>
  86          *         <li>its buffer has unsaved changes, or
  87          *         <li>one of its descendants has unsaved changes, or
  88          *         <li>a working copy has been created on one of this element's
  89          *         children and has not yet destroyed
  90          *         </ul>
  91          */
  92         boolean hasUnsavedChanges() throws JavaModelException;
  93
  94         /**
  95          * Returns whether the element is consistent with its underlying resource or
  96          * buffer. The element is consistent when opened, and is consistent if the
  97          * underlying resource or buffer has not been modified since it was last
  98          * consistent.
  99          *
 100          * <p>
 101          * NOTE: Child consistency is not considered. For example, a package
 102          * fragment responds <code>true</code> when it knows about all of its
 103          * compilation units present in its underlying folder. However, one or more
 104          * of the compilation units could be inconsistent.
 105          *
 106          * @exception JavaModelException
 107          *                if this element does not exist or if an exception occurs
 108          *                while accessing its corresponding resource.
 109          * @return true if the element is consistent with its underlying resource or
 110          *         buffer, false otherwise.
 111          * @see IOpenable#makeConsistent
 112          */
 113         boolean isConsistent() throws JavaModelException;
 114
 115         /**
 116          * Returns whether this openable is open. This is a handle-only method.
 117          *
 118          * @return true if this openable is open, false otherwise
 119          */
 120         boolean isOpen();
 121
 122         /**
 123          * Opens this element and all parent elements that are not already open. For
 124          * compilation units, a buffer is opened on the contents of the underlying
 125          * resource.
 126          *
 127          * <p>
 128          * Note: although <code>open</code> is exposed in the API, clients are not
 129          * expected to open and close elements - the Java model does this
 130          * automatically as elements are accessed.
 131          *
 132          * @param progress
 133          *            the given progress monitor
 134          * @exception JavaModelException
 135          *                if an error occurs accessing the contents of its
 136          *                underlying resource. Reasons include:
 137          *                <ul>
 138          *                <li>This Java element does not exist
 139          *                (ELEMENT_DOES_NOT_EXIST)</li>
 140          *                </ul>
 141          */
 142         public void open(IProgressMonitor progress) throws JavaModelException;
 143
 144         /**
 145          * Makes this element consistent with its underlying resource or buffer by
 146          * updating the element's structure and properties as necessary.
 147          *
 148          * @param progress
 149          *            the given progress monitor
 150          * @exception JavaModelException
 151          *                if the element is unable to access the contents of its
 152          *                underlying resource. Reasons include:
 153          *                <ul>
 154          *                <li>This Java element does not exist
 155          *                (ELEMENT_DOES_NOT_EXIST)</li>
 156          *                </ul>
 157          * @see IOpenable#isConsistent
 158          */
 159         void makeConsistent(IProgressMonitor progress) throws JavaModelException;
 160
 161         /**
 162          * Opens this element and all parent elements that are not already open. For
 163          * compilation units, a buffer is opened on the contents of the underlying
 164          * resource.
 165          *
 166          * <p>
 167          * Note: although <code>open</code> is exposed in the API, clients are not
 168          * expected to open and close elements - the Java model does this
 169          * automatically as elements are accessed.
 170          *
 171          * @param progress
 172          *            the given progress monitor
 173          * @exception JavaModelException
 174          *                if an error occurs accessing the contents of its
 175          *                underlying resource. Reasons include:
 176          *                <ul>
 177          *                <li>This Java element does not exist
 178          *                (ELEMENT_DOES_NOT_EXIST)</li>
 179          *                </ul>
 180          */
 181         // public void open(IProgressMonitor progress) throws JavaModelException;
 182         /**
 183          * Saves any changes in this element's buffer to its underlying resource via
 184          * a workspace resource operation. This has no effect if the element has no
 185          * underlying buffer, or if there are no unsaved changed in the buffer.
 186          * <p>
 187          * The <code>force</code> parameter controls how this method deals with
 188          * cases where the workbench is not completely in sync with the local file
 189          * system. If <code>false</code> is specified, this method will only
 190          * attempt to overwrite a corresponding file in the local file system
 191          * provided it is in sync with the workbench. This option ensures there is
 192          * no unintended data loss; it is the recommended setting. However, if
 193          * <code>true</code> is specified, an attempt will be made to write a
 194          * corresponding file in the local file system, overwriting any existing one
 195          * if need be. In either case, if this method succeeds, the resource will be
 196          * marked as being local (even if it wasn't before).
 197          * <p>
 198          * As a result of this operation, the element is consistent with its
 199          * underlying resource or buffer.
 200          *
 201          * @param progress
 202          *            the given progress monitor
 203          * @param force
 204          *            it controls how this method deals with cases where the
 205          *            workbench is not completely in sync with the local file system
 206          * @exception JavaModelException
 207          *                if an error occurs accessing the contents of its
 208          *                underlying resource. Reasons include:
 209          *                <ul>
 210          *                <li>This Java element does not exist
 211          *                (ELEMENT_DOES_NOT_EXIST)</li>
 212          *                <li>This Java element is read-only (READ_ONLY)</li>
 213          *                </ul>
 214          */
 215         public void save(IProgressMonitor progress, boolean force)
 216                         throws JavaModelException;
 217
 218 }