IOpenable


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.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 {@link #isConsistent} and {@link #makeConsistent(IProgressMonitor)}.
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 {@link IOpenable}.
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 {@link #close} 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   * Finds and returns the recommended line separator for this element.
59   * The element's buffer is first searched and the first line separator in this buffer is returned if any.
60   * Otherwise the preference {@link org.eclipse.core.runtime.Platform#PREF_LINE_SEPARATOR} 
61   * on this element's project or workspace is returned.
62   * Finally if no such preference is set, the system line separator is returned.
63   * 
64   * @return the recommended line separator for this element
65   * @exception JavaModelException if this element does not exist or if an
66   *      exception occurs while accessing its corresponding resource.
67   * @since 3.2
68   */
69  public String   findRecommendedLineSeparator() throws JavaModelException;
70  /**
71   * Returns the buffer opened for this element, or <code>null</code>
72   * if this element does not have a buffer.
73   *
74   * @exception JavaModelException if this element does not exist or if an
75   *      exception occurs while accessing its corresponding resource.
76   * @return the buffer opened for this element, or <code>null</code>
77   * if this element does not have a buffer
78   */
79  public IBuffer getBuffer() throws JavaModelException;
80  /**
81   * Returns <code>true</code> if this element is open and:
82   * <ul>
83   * <li>its buffer has unsaved changes, or
84   * <li>one of its descendants has unsaved changes, or
85   * <li>a working copy has been created on one of this
86   * element's children and has not yet destroyed
87   * </ul>
88   *
89   * @exception JavaModelException if this element does not exist or if an
90   *      exception occurs while accessing its corresponding resource.
91   * @return <code>true</code> if this element is open and:
92   * <ul>
93   * <li>its buffer has unsaved changes, or
94   * <li>one of its descendants has unsaved changes, or
95   * <li>a working copy has been created on one of this
96   * element's children and has not yet destroyed
97   * </ul>
98   */
99  boolean hasUnsavedChanges() throws JavaModelException;
100 /**
101  * Returns whether the element is consistent with its underlying resource or buffer.
102  * The element is consistent when opened, and is consistent if the underlying resource
103  * or buffer has not been modified since it was last consistent.
104  *
105  * <p>NOTE: Child consistency is not considered. For example, a package fragment
106  * responds <code>true</code> when it knows about all of its
107  * compilation units present in its underlying folder. However, one or more of
108  * the compilation units could be inconsistent.
109  *
110  * @exception JavaModelException if this element does not exist or if an
111  *      exception occurs while accessing its corresponding resource.
112  * @return true if the element is consistent with its underlying resource or buffer, false otherwise.
113  * @see IOpenable#makeConsistent(IProgressMonitor)
114  */
115 boolean isConsistent() throws JavaModelException;
116 /**
117  * Returns whether this openable is open. This is a handle-only method.
118  * @return true if this openable is open, false otherwise
119  */
120 boolean isOpen();
121 /**
122  * Makes this element consistent with its underlying resource or buffer 
123  * by updating the element's structure and properties as necessary.
124  *<p>
125  * Note: Using this functionality on a working copy will interfere with any
126  * subsequent reconciling operation. Indeed, the next
127  * {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} or
128  * {@link ICompilationUnit#reconcile(int, boolean, boolean, WorkingCopyOwner, IProgressMonitor)}
129  * operation will not account for changes which occurred before an
130  * explicit use of {@link #makeConsistent(IProgressMonitor)}
131  * <p>
132  * @param progress the given progress monitor
133  * @exception JavaModelException if the element is unable to access the contents
134  *      of its underlying resource. Reasons include:
135  * <ul>
136  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
137  * </ul>
138  * @see IOpenable#isConsistent()
139  * @see ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)
140  */
141 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
142 /**
143  * Opens this element and all parent elements that are not already open.
144  * For compilation units, a buffer is opened on the contents of the underlying resource.
145  *
146  * <p>Note: although {@link #open} is exposed in the API, clients are
147  * not expected to open and close elements - the Java model does this automatically
148  * as elements are accessed.
149  *
150  * @param progress the given progress monitor
151  * @exception JavaModelException if an error occurs accessing the contents
152  *      of its underlying resource. Reasons include:
153  * <ul>
154  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
155  * </ul>
156  */
157 public void open(IProgressMonitor progress) throws JavaModelException;
158 /**
159  * Saves any changes in this element's buffer to its underlying resource
160  * via a workspace resource operation. This has no effect if the element has no underlying
161  * buffer, or if there are no unsaved changed in the buffer.
162  * <p>
163  * The <code>force</code> parameter controls how this method deals with
164  * cases where the workbench is not completely in sync with the local file system.
165  * If <code>false</code> is specified, this method will only attempt
166  * to overwrite a corresponding file in the local file system provided
167  * it is in sync with the workbench. This option ensures there is no 
168  * unintended data loss; it is the recommended setting.
169  * However, if <code>true</code> is specified, an attempt will be made
170  * to write a corresponding file in the local file system, 
171  * overwriting any existing one if need be.
172  * In either case, if this method succeeds, the resource will be marked 
173  * as being local (even if it wasn't before).
174  * <p>
175  * As a result of this operation, the element is consistent with its underlying 
176  * resource or buffer. 
177  *
178  * @param progress the given progress monitor
179  * @param force it controls how this method deals with
180  * cases where the workbench is not completely in sync with the local file system
181  * @exception JavaModelException if an error occurs accessing the contents
182  *      of its underlying resource. Reasons include:
183  * <ul>
184  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
185  *  <li>This Java element is read-only (READ_ONLY)</li>
186  * </ul>
187  */
188 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
189 }
190
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags