X-Git-Url: http://secure.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 new file mode 100644 index 0000000..e0e17e3 --- /dev/null +++ b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java @@ -0,0 +1,168 @@ +/******************************************************************************* + * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Common Public License v0.5 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/cpl-v05.html + * + * Contributors: + * IBM Corporation - initial API and implementation + ******************************************************************************/ +package net.sourceforge.phpdt.core; + +import org.eclipse.core.runtime.IProgressMonitor; + +/** + * 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). + *

+ * 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. + *

+ *

+ * 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. + *

+ */ +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(); +/** + * 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; +}