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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.runtime.IProgressMonitor;
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>.
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.
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.
41 * This interface is not intended to be implemented by clients.
44 public interface IOpenable {
47 * Closes this element and its buffer (if any). Closing an element which is
48 * not open has no effect.
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.
55 * @exception JavaModelException
56 * if an error occurs closing this element
58 public void close() throws JavaModelException;
61 * Returns the buffer opened for this element, or <code>null</code> if
62 * this element does not have a buffer.
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
70 public IBuffer getBuffer() throws JavaModelException;
73 * Returns <code>true</code> if this element is open and:
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
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:
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
92 boolean hasUnsavedChanges() throws JavaModelException;
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
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.
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
113 boolean isConsistent() throws JavaModelException;
116 * Returns whether this openable is open. This is a handle-only method.
118 * @return true if this openable is open, false otherwise
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
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.
133 * the given progress monitor
134 * @exception JavaModelException
135 * if an error occurs accessing the contents of its
136 * underlying resource. Reasons include:
138 * <li>This Java element does not exist
139 * (ELEMENT_DOES_NOT_EXIST)</li>
142 public void open(IProgressMonitor progress) throws JavaModelException;
145 * Makes this element consistent with its underlying resource or buffer by
146 * updating the element's structure and properties as necessary.
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:
154 * <li>This Java element does not exist
155 * (ELEMENT_DOES_NOT_EXIST)</li>
157 * @see IOpenable#isConsistent
159 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
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
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.
172 * the given progress monitor
173 * @exception JavaModelException
174 * if an error occurs accessing the contents of its
175 * underlying resource. Reasons include:
177 * <li>This Java element does not exist
178 * (ELEMENT_DOES_NOT_EXIST)</li>
181 // public void open(IProgressMonitor progress) throws JavaModelException;
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.
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).
198 * As a result of this operation, the element is consistent with its
199 * underlying resource or buffer.
202 * the given progress monitor
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:
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>
215 public void save(IProgressMonitor progress, boolean force)
216 throws JavaModelException;