X-Git-Url: http://git.phpeclipse.com diff --git a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java index 9424f3a..aead99c 100644 --- a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java +++ b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java @@ -12,31 +12,30 @@ package net.sourceforge.phpdt.core; import org.eclipse.core.runtime.IProgressMonitor; - /** - * Common protocol for Java elements that must be opened before they can be + * Common protocol for Java elements that must be opened before they can be * navigated or modified. Opening a textual element (such as a compilation unit) - * involves opening a buffer on its contents. While open, any changes to the buffer - * can be reflected in the element's structure; - * see isConsistent and makeConsistent(IProgressMonitor). + * involves opening a buffer on its contents. While open, any changes to the + * buffer can be reflected in the element's structure; see + * isConsistent and makeConsistent(IProgressMonitor). *

- * To reduce complexity in clients, elements are automatically opened - * by the Java model as element properties are accessed. The Java model maintains - * an LRU cache of open elements, and automatically closes elements as they - * are swapped out of the cache to make room for other elements. Elements with + * To reduce complexity in clients, elements are automatically opened by the + * Java model as element properties are accessed. The Java model maintains an + * LRU cache of open elements, and automatically closes elements as they are + * swapped out of the cache to make room for other elements. Elements with * unsaved changes are never removed from the cache, and thus, if the client - * maintains many open elements with unsaved - * changes, the LRU cache can grow in size (in this case the cache is not - * bounded). However, as elements are saved, the cache will shrink back to its - * original bounded size. + * maintains many open elements with unsaved changes, the LRU cache can grow in + * size (in this case the cache is not bounded). However, as elements are saved, + * the cache will shrink back to its original bounded size. *

*

- * To open an element, all openable parent elements must be open. - * The Java model automatically opens parent elements, as it automatically opens elements. - * Opening an element may provide access to direct children and other descendants, - * but does not automatically open any descendents which are themselves IOpenable. - * For example, opening a compilation unit provides access to all its constituent elements, - * but opening a package fragment does not open all compilation units in the package fragment. + * To open an element, all openable parent elements must be open. The Java model + * automatically opens parent elements, as it automatically opens elements. + * Opening an element may provide access to direct children and other + * descendants, but does not automatically open any descendents which are + * themselves IOpenable. For example, opening a compilation unit + * provides access to all its constituent elements, but opening a package + * fragment does not open all compilation units in the package fragment. *

*

* This interface is not intended to be implemented by clients. @@ -44,143 +43,176 @@ import org.eclipse.core.runtime.IProgressMonitor; */ public interface IOpenable { -/** - * Closes this element and its buffer (if any). - * Closing an element which is not open has no effect. - * - *

Note: although close is exposed in the API, clients are - * not expected to open and close elements - the Java model does this automatically - * as elements are accessed. - * - * @exception JavaModelException if an error occurs closing this element - */ -public void close() throws JavaModelException; -/** - * Returns the buffer opened for this element, or null - * if this element does not have a buffer. - * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource. - * @return the buffer opened for this element, or null - * if this element does not have a buffer - */ -public IBuffer getBuffer() throws JavaModelException; -/** - * Returns true if this element is open and: - *

- * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource. - * @return true if this element is open and: - * - */ -boolean hasUnsavedChanges() throws JavaModelException; -/** - * Returns whether the element is consistent with its underlying resource or buffer. - * The element is consistent when opened, and is consistent if the underlying resource - * or buffer has not been modified since it was last consistent. - * - *

NOTE: Child consistency is not considered. For example, a package fragment - * responds true when it knows about all of its - * compilation units present in its underlying folder. However, one or more of - * the compilation units could be inconsistent. - * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource. - * @return true if the element is consistent with its underlying resource or buffer, false otherwise. - * @see IOpenable#makeConsistent - */ -boolean isConsistent() throws JavaModelException; -/** - * Returns whether this openable is open. This is a handle-only method. - * @return true if this openable is open, false otherwise - */ -boolean isOpen(); -/** - * Opens this element and all parent elements that are not already open. - * For compilation units, a buffer is opened on the contents of the underlying resource. - * - *

Note: although open is exposed in the API, clients are - * not expected to open and close elements - the Java model does this automatically - * as elements are accessed. - * - * @param progress the given progress monitor - * @exception JavaModelException if an error occurs accessing the contents - * of its underlying resource. Reasons include: - *

- */ -public void open(IProgressMonitor progress) throws JavaModelException; -/** - * Makes this element consistent with its underlying resource or buffer - * by updating the element's structure and properties as necessary. - * - * @param progress the given progress monitor - * @exception JavaModelException if the element is unable to access the contents - * of its underlying resource. Reasons include: - * - * @see IOpenable#isConsistent - */ -void makeConsistent(IProgressMonitor progress) throws JavaModelException; -/** - * Opens this element and all parent elements that are not already open. - * For compilation units, a buffer is opened on the contents of the underlying resource. - * - *

Note: although open is exposed in the API, clients are - * not expected to open and close elements - the Java model does this automatically - * as elements are accessed. - * - * @param progress the given progress monitor - * @exception JavaModelException if an error occurs accessing the contents - * of its underlying resource. Reasons include: - *

- */ -//public void open(IProgressMonitor progress) throws JavaModelException; -/** - * Saves any changes in this element's buffer to its underlying resource - * via a workspace resource operation. This has no effect if the element has no underlying - * buffer, or if there are no unsaved changed in the buffer. - *

- * The force parameter controls how this method deals with - * cases where the workbench is not completely in sync with the local file system. - * If false is specified, this method will only attempt - * to overwrite a corresponding file in the local file system provided - * it is in sync with the workbench. This option ensures there is no - * unintended data loss; it is the recommended setting. - * However, if true is specified, an attempt will be made - * to write a corresponding file in the local file system, - * overwriting any existing one if need be. - * In either case, if this method succeeds, the resource will be marked - * as being local (even if it wasn't before). - *

- * As a result of this operation, the element is consistent with its underlying - * resource or buffer. - * - * @param progress the given progress monitor - * @param force it controls how this method deals with - * cases where the workbench is not completely in sync with the local file system - * @exception JavaModelException if an error occurs accessing the contents - * of its underlying resource. Reasons include: - *

- */ -public void save(IProgressMonitor progress, boolean force) throws JavaModelException; + /** + * Closes this element and its buffer (if any). Closing an element which is + * not open has no effect. + * + *

+ * Note: although close is exposed in the API, clients are + * not expected to open and close elements - the Java model does this + * automatically as elements are accessed. + * + * @exception JavaModelException + * if an error occurs closing this element + */ + public void close() throws JavaModelException; + + /** + * Returns the buffer opened for this element, or null if + * this element does not have a buffer. + * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource. + * @return the buffer opened for this element, or null if + * this element does not have a buffer + */ + public IBuffer getBuffer() throws JavaModelException; + + /** + * Returns true if this element is open and: + *

+ * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource. + * @return true if this element is open and: + * + */ + boolean hasUnsavedChanges() throws JavaModelException; + + /** + * Returns whether the element is consistent with its underlying resource or + * buffer. The element is consistent when opened, and is consistent if the + * underlying resource or buffer has not been modified since it was last + * consistent. + * + *

+ * NOTE: Child consistency is not considered. For example, a package + * fragment responds true when it knows about all of its + * compilation units present in its underlying folder. However, one or more + * of the compilation units could be inconsistent. + * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource. + * @return true if the element is consistent with its underlying resource or + * buffer, false otherwise. + * @see IOpenable#makeConsistent + */ + boolean isConsistent() throws JavaModelException; + + /** + * Returns whether this openable is open. This is a handle-only method. + * + * @return true if this openable is open, false otherwise + */ + boolean isOpen(); + + /** + * Opens this element and all parent elements that are not already open. For + * compilation units, a buffer is opened on the contents of the underlying + * resource. + * + *

+ * Note: although open is exposed in the API, clients are not + * expected to open and close elements - the Java model does this + * automatically as elements are accessed. + * + * @param progress + * the given progress monitor + * @exception JavaModelException + * if an error occurs accessing the contents of its + * underlying resource. Reasons include: + *

+ */ + public void open(IProgressMonitor progress) throws JavaModelException; + + /** + * Makes this element consistent with its underlying resource or buffer by + * updating the element's structure and properties as necessary. + * + * @param progress + * the given progress monitor + * @exception JavaModelException + * if the element is unable to access the contents of its + * underlying resource. Reasons include: + * + * @see IOpenable#isConsistent + */ + void makeConsistent(IProgressMonitor progress) throws JavaModelException; + + /** + * Opens this element and all parent elements that are not already open. For + * compilation units, a buffer is opened on the contents of the underlying + * resource. + * + *

+ * Note: although open is exposed in the API, clients are not + * expected to open and close elements - the Java model does this + * automatically as elements are accessed. + * + * @param progress + * the given progress monitor + * @exception JavaModelException + * if an error occurs accessing the contents of its + * underlying resource. Reasons include: + *

+ */ + // public void open(IProgressMonitor progress) throws JavaModelException; + /** + * Saves any changes in this element's buffer to its underlying resource via + * a workspace resource operation. This has no effect if the element has no + * underlying buffer, or if there are no unsaved changed in the buffer. + *

+ * The force parameter controls how this method deals with + * cases where the workbench is not completely in sync with the local file + * system. If false is specified, this method will only + * attempt to overwrite a corresponding file in the local file system + * provided it is in sync with the workbench. This option ensures there is + * no unintended data loss; it is the recommended setting. However, if + * true is specified, an attempt will be made to write a + * corresponding file in the local file system, overwriting any existing one + * if need be. In either case, if this method succeeds, the resource will be + * marked as being local (even if it wasn't before). + *

+ * As a result of this operation, the element is consistent with its + * underlying resource or buffer. + * + * @param progress + * the given progress monitor + * @param force + * it controls how this method deals with cases where the + * workbench is not completely in sync with the local file system + * @exception JavaModelException + * if an error occurs accessing the contents of its + * underlying resource. Reasons include: + *

+ */ + public void save(IProgressMonitor progress, boolean force) + throws JavaModelException; }