e0e17e3a66ce288868dff895e46ef6d619bc8458
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / IOpenable.java
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
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 buffer
19  * can be reflected in the element's structure; 
20  * see <code>isConsistent</code> and <code>makeConsistent(IProgressMonitor)</code>.
21  * <p>
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.
31  * </p>
32  * <p>
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.
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).
48  * Closing an element which is not open has no effect.
49  *
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.
53  *
54  * @exception JavaModelException if an error occurs closing this element
55  */
56 public void close() throws JavaModelException;
57 /**
58  * Returns the buffer opened for this element, or <code>null</code>
59  * if this element does not have a buffer.
60  *
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
65  */
66 public IBuffer getBuffer() throws JavaModelException;
67 /**
68  * Returns <code>true</code> if this element is open and:
69  * <ul>
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
74  * </ul>
75  *
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:
79  * <ul>
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
84  * </ul>
85  */
86 boolean hasUnsavedChanges() throws JavaModelException;
87 /**
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.
91  *
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.
96  *
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
101  */
102 boolean isConsistent() throws JavaModelException;
103 /**
104  * Returns whether this openable is open. This is a handle-only method.
105  * @return true if this openable is open, false otherwise
106  */
107 boolean isOpen();
108 /**
109  * Makes this element consistent with its underlying resource or buffer 
110  * by updating the element's structure and properties as necessary.
111  *
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:
115  * <ul>
116  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
117  * </ul>
118  * @see IOpenable#isConsistent
119  */
120 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
121 /**
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.
124  *
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.
128  *
129  * @param progress the given progress monitor
130  * @exception JavaModelException if an error occurs accessing the contents
131  *              of its underlying resource. Reasons include:
132  * <ul>
133  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
134  * </ul>
135  */
136 public void open(IProgressMonitor progress) throws JavaModelException;
137 /**
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.
141  * <p>
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).
153  * <p>
154  * As a result of this operation, the element is consistent with its underlying 
155  * resource or buffer. 
156  *
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:
162  * <ul>
163  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
164  *  <li>This Java element is read-only (READ_ONLY)</li>
165  * </ul>
166  */
167 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
168 }