1 /*******************************************************************************
2 * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v0.5
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v05.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 buffer
19 * can be reflected in the element's structure;
20 * see <code>isConsistent</code> and <code>makeConsistent(IProgressMonitor)</code>.
22 * To reduce complexity in clients, elements are automatically opened
23 * by the Java model as element properties are accessed. The Java model maintains
24 * an LRU cache of open elements, and automatically closes elements as they
25 * are 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
28 * changes, the LRU cache can grow in size (in this case the cache is not
29 * bounded). However, as elements are saved, the cache will shrink back to its
30 * original bounded size.
33 * To open an element, all openable parent elements must be open.
34 * The Java model automatically opens parent elements, as it automatically opens elements.
35 * Opening an element may provide access to direct children and other descendants,
36 * but does not automatically open any descendents which are themselves <code>IOpenable</code>.
37 * For example, opening a compilation unit provides access to all its constituent elements,
38 * but opening a package 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).
48 * Closing an element which is not open has no effect.
50 * <p>Note: although <code>close</code> is exposed in the API, clients are
51 * not expected to open and close elements - the Java model does this automatically
52 * as elements are accessed.
54 * @exception JavaModelException if an error occurs closing this element
56 public void close() throws JavaModelException;
58 * Returns the buffer opened for this element, or <code>null</code>
59 * if this element does not have a buffer.
61 * @exception JavaModelException if this element does not exist or if an
62 * exception occurs while accessing its corresponding resource.
63 * @return the buffer opened for this element, or <code>null</code>
64 * if this element does not have a buffer
66 public IBuffer getBuffer() throws JavaModelException;
68 * Returns <code>true</code> if this element is open and:
70 * <li>its buffer has unsaved changes, or
71 * <li>one of its descendants has unsaved changes, or
72 * <li>a working copy has been created on one of this
73 * element's children and has not yet destroyed
76 * @exception JavaModelException if this element does not exist or if an
77 * exception occurs while accessing its corresponding resource.
78 * @return <code>true</code> if this element is open and:
80 * <li>its buffer has unsaved changes, or
81 * <li>one of its descendants has unsaved changes, or
82 * <li>a working copy has been created on one of this
83 * element's children and has not yet destroyed
86 boolean hasUnsavedChanges() throws JavaModelException;
88 * Returns whether the element is consistent with its underlying resource or buffer.
89 * The element is consistent when opened, and is consistent if the underlying resource
90 * or buffer has not been modified since it was last consistent.
92 * <p>NOTE: Child consistency is not considered. For example, a package fragment
93 * responds <code>true</code> when it knows about all of its
94 * compilation units present in its underlying folder. However, one or more of
95 * the compilation units could be inconsistent.
97 * @exception JavaModelException if this element does not exist or if an
98 * exception occurs while accessing its corresponding resource.
99 * @return true if the element is consistent with its underlying resource or buffer, false otherwise.
100 * @see IOpenable#makeConsistent
102 boolean isConsistent() throws JavaModelException;
104 * Returns whether this openable is open. This is a handle-only method.
105 * @return true if this openable is open, false otherwise
109 * Makes this element consistent with its underlying resource or buffer
110 * by updating the element's structure and properties as necessary.
112 * @param progress the given progress monitor
113 * @exception JavaModelException if the element is unable to access the contents
114 * of its underlying resource. Reasons include:
116 * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
118 * @see IOpenable#isConsistent
120 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
122 * Opens this element and all parent elements that are not already open.
123 * For compilation units, a buffer is opened on the contents of the underlying resource.
125 * <p>Note: although <code>open</code> is exposed in the API, clients are
126 * not expected to open and close elements - the Java model does this automatically
127 * as elements are accessed.
129 * @param progress the given progress monitor
130 * @exception JavaModelException if an error occurs accessing the contents
131 * of its underlying resource. Reasons include:
133 * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
136 public void open(IProgressMonitor progress) throws JavaModelException;
138 * Saves any changes in this element's buffer to its underlying resource
139 * via a workspace resource operation. This has no effect if the element has no underlying
140 * buffer, or if there are no unsaved changed in the buffer.
142 * The <code>force</code> parameter controls how this method deals with
143 * cases where the workbench is not completely in sync with the local file system.
144 * If <code>false</code> is specified, this method will only attempt
145 * to overwrite a corresponding file in the local file system provided
146 * it is in sync with the workbench. This option ensures there is no
147 * unintended data loss; it is the recommended setting.
148 * However, if <code>true</code> is specified, an attempt will be made
149 * to write a corresponding file in the local file system,
150 * overwriting any existing one if need be.
151 * In either case, if this method succeeds, the resource will be marked
152 * as being local (even if it wasn't before).
154 * As a result of this operation, the element is consistent with its underlying
155 * resource or buffer.
157 * @param progress the given progress monitor
158 * @param force it controls how this method deals with
159 * cases where the workbench is not completely in sync with the local file system
160 * @exception JavaModelException if an error occurs accessing the contents
161 * of its underlying resource. Reasons include:
163 * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
164 * <li>This Java element is read-only (READ_ONLY)</li>
167 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;