KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > IWorkingCopy


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.resources.IMarker;
14 import org.eclipse.core.resources.IResource;
15 import org.eclipse.core.runtime.IProgressMonitor;
16
17 /**
18  * Common protocol for Java elements that support working copies.
19  * <p>
20  * A working copy of a Java element acts just like a regular element (handle),
21  * except it is not attached to an underlying resource. A working copy is not
22  * visible to the rest of the Java model. Changes in a working copy's
23  * buffer are not realized in a resource. To bring the Java model up-to-date with a working
24  * copy's contents, an explicit commit must be performed on the working copy.
25  * Other operations performed on a working copy update the
26  * contents of the working copy's buffer but do not commit the contents
27  * of the working copy.
28  * </p>
29  * <p>
30  * Note: The contents of a working copy is determined when a working
31  * copy is created, based on the current content of the element the working
32  * copy is created from. If a working copy is an <code>IOpenable</code> and is explicitly
33  * closed, the working copy's buffer will be thrown away. However, clients should not
34  * explicitly open and close working copies.
35  * </p>
36  * <p>
37  * The client that creates a working copy is responsible for
38  * destroying the working copy. The Java model will never automatically
39  * destroy or close a working copy. (Note that destroying a working copy
40  * does not commit it to the model, it only frees up the memory occupied by
41  * the element). After a working copy is destroyed, the working copy cannot
42  * be accessed again. Non-handle methods will throw a
43  * <code>JavaModelException</code> indicating the Java element does not exist.
44  * </p>
45  * <p>
46  * A working copy cannot be created from another working copy.
47  * Calling <code>getWorkingCopy</code> on a working copy returns the receiver.
48  * </p>
49  * <p>
50  * This interface is not intended to be implemented by clients.
51  * </p>
52  * @deprecated Use {@link ICompilationUnit} instead
53  */
54 public interface IWorkingCopy {
55     
56     /**
57      * Commits the contents of this working copy to its original element
58      * and underlying resource, bringing the Java model up-to-date with
59      * the current contents of the working copy.
60      *
61      * <p>It is possible that the contents of the original resource have changed
62      * since this working copy was created, in which case there is an update conflict.
63      * The value of the <code>force</code> parameter effects the resolution of
64      * such a conflict:<ul>
65      * <li> <code>true</code> - in this case the contents of this working copy are applied to
66      * the underlying resource even though this working copy was created before
67      * a subsequent change in the resource</li>
68      * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
69      * </ul>
70      * <p>
71      * Since 2.1, a working copy can be created on a not-yet existing compilation
72      * unit. In particular, such a working copy can then be committed in order to create
73      * the corresponding compilation unit.
74      * </p>
75      * @param force a flag to handle the cases when the contents of the original resource have changed
76      * since this working copy was created
77      * @param monitor the given progress monitor
78      * @exception JavaModelException if this working copy could not commit. Reasons include:
79      * <ul>
80      * <li> A <code>CoreException</code> occurred while updating an underlying resource
81      * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
82      * <li> A update conflict (described above) (UPDATE_CONFLICT)
83      * </ul>
84      * @deprecated Use {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} instead.
85      */
86     void commit(boolean force, IProgressMonitor monitor) throws JavaModelException;
87     
88     /**
89      * Destroys this working copy, closing its buffer and discarding
90      * its structure. Subsequent attempts to access non-handle information
91      * for this working copy will result in <code>IJavaModelException</code>s. Has
92      * no effect if this element is not a working copy.
93      * <p>
94      * If this working copy is shared, it is destroyed only when the number of calls to
95      * <code>destroy()</code> is the same as the number of calls to <code>
96      * getSharedWorkingCopy(IProgressMonitor, IBufferFactory)</code>.
97      * </p><p>
98      * When it is destroyed, a REMOVED IJavaElementDelta is reported on this
99      * working copy.
100      * </p>
101      * @deprecated Use {@link ICompilationUnit#discardWorkingCopy()} instead.
102      */
103     void destroy();
104     
105     /**
106      * Finds the shared working copy for this element, given a <code>IBuffer</code> factory.
107      * If no working copy has been created for this element associated with this
108      * buffer factory, returns <code>null</code>.
109      * <p>
110      * Users of this method must not destroy the resulting working copy.
111      *
112      * @param bufferFactory the given <code>IBuffer</code> factory
113      * @return the found shared working copy for this element, <code>null</code> if none
114      * @see IBufferFactory
115      * @since 2.0
116      *
117      * @deprecated Use {@link ICompilationUnit#findWorkingCopy(WorkingCopyOwner)} instead.
118      */
119     IJavaElement findSharedWorkingCopy(IBufferFactory bufferFactory);
120
121     /**
122      * Returns the original element the specified working copy element was created from,
123      * or <code>null</code> if this is not a working copy element. This is a handle
124      * only method, the returned element may or may not exist.
125      *
126      * @param workingCopyElement the specified working copy element
127      * @return the original element the specified working copy element was created from,
128      * or <code>null</code> if this is not a working copy element
129      *
130      * @deprecated Use {@link IJavaElement#getPrimaryElement()} instead.
131      */
132     IJavaElement getOriginal(IJavaElement workingCopyElement);
133     
134     /**
135      * Returns the original element this working copy was created from,
136      * or <code>null</code> if this is not a working copy.
137      *
138      * @return the original element this working copy was created from,
139      * or <code>null</code> if this is not a working copy
140      *
141      * @deprecated Use {@link ICompilationUnit#findPrimaryType()} instead.
142      */
143     IJavaElement getOriginalElement();
144     
145     /**
146      * Finds the elements in this compilation unit that correspond to
147      * the given element.
148      * An element A corresponds to an element B if:
149      * <ul>
150      * <li>A has the same element name as B.
151      * <li>If A is a method, A must have the same number of arguments as
152      * B and the simple names of the argument types must be equals.
153      * <li>The parent of A corresponds to the parent of B recursively up to
154      * their respective compilation units.
155      * <li>A exists.
156      * </ul>
157      * Returns <code>null</code> if no such java elements can be found
158      * or if the given element is not included in a compilation unit.
159      *
160      * @param element the given element
161      * @return the found elements in this compilation unit that correspond to the given element
162      * @since 2.0
163      *
164      * @deprecated Use {@link ICompilationUnit#findElements(IJavaElement)} instead.
165      */
166     IJavaElement[] findElements(IJavaElement element);
167     
168     /**
169      * Finds the primary type of this compilation unit (that is, the type with the same name as the
170      * compilation unit), or <code>null</code> if no such a type exists.
171      *
172      * @return the found primary type of this compilation unit, or <code>null</code> if no such a type exists
173      * @since 2.0
174      *
175      * @deprecated Use {@link ITypeRoot#findPrimaryType()} instead.
176      */
177     IType findPrimaryType();
178     
179     /**
180      * Returns a shared working copy on this element using the given factory to create
181      * the buffer, or this element if this element is already a working copy.
182      * This API can only answer an already existing working copy if it is based on the same
183      * original compilation unit AND was using the same buffer factory (that is, as defined by <code>Object.equals</code>).
184      * <p>
185      * The life time of a shared working copy is as follows:
186      * <ul>
187      * <li>The first call to <code>getSharedWorkingCopy(...)</code> creates a new working copy for this
188      * element</li>
189      * <li>Subsequent calls increment an internal counter.</li>
190      * <li>A call to <code>destroy()</code> decrements the internal counter.</li>
191      * <li>When this counter is 0, the working copy is destroyed.
192      * </ul>
193      * So users of this method must destroy exactly once the working copy.
194      * <p>
195      * Note that the buffer factory will be used for the life time of this working copy, that is if the
196      * working copy is closed then reopened, this factory will be used.
197      * The buffer will be automatically initialized with the original's compilation unit content
198      * upon creation.
199      * <p>
200      * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
201      * working copy.
202      *
203      * @param monitor a progress monitor used to report progress while opening this compilation unit
204      * or <code>null</code> if no progress should be reported
205      * @param factory the factory that creates a buffer that is used to get the content of the working copy
206      * or <code>null</code> if the internal factory should be used
207      * @param problemRequestor a requestor which will get notified of problems detected during
208      * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
209      * that the client is not interested in problems.
210      * @exception JavaModelException if the contents of this element can
211      * not be determined.
212      * @return a shared working copy on this element using the given factory to create
213      * the buffer, or this element if this element is already a working copy
214      * @see IBufferFactory
215      * @see IProblemRequestor
216      * @since 2.0
217      *
218      * @deprecated Use {@link ICompilationUnit#getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)} instead.
219      */
220     IJavaElement getSharedWorkingCopy(
221         IProgressMonitor monitor,
222         IBufferFactory factory,
223         IProblemRequestor problemRequestor)
224         throws JavaModelException;
225         
226     /**
227      * Returns a new working copy of this element if this element is not
228      * a working copy, or this element if this element is already a working copy.
229      * <p>
230      * Note: if intending to share a working copy amongst several clients, then
231      * <code>#getSharedWorkingCopy</code> should be used instead.
232      * </p><p>
233      * When the working copy instance is created, an ADDED IJavaElementDelta is
234      * reported on this working copy.
235      * </p><p>
236      * Since 2.1, a working copy can be created on a not-yet existing compilation
237      * unit. In particular, such a working copy can then be committed in order to create
238      * the corresponding compilation unit.
239      * </p>
240      * @exception JavaModelException if the contents of this element can
241      * not be determined.
242      * @return a new working copy of this element if this element is not
243      * a working copy, or this element if this element is already a working copy
244      *
245      * @deprecated Use {@link ICompilationUnit#getWorkingCopy(IProgressMonitor)} instead.
246      */
247     IJavaElement getWorkingCopy() throws JavaModelException;
248     
249     /**
250      * Returns a new working copy of this element using the given factory to create
251      * the buffer, or this element if this element is already a working copy.
252      * Note that this factory will be used for the life time of this working copy, that is if the
253      * working copy is closed then reopened, this factory will be reused.
254      * The buffer will be automatically initialized with the original's compilation unit content
255      * upon creation.
256      * <p>
257      * Note: if intending to share a working copy amongst several clients, then
258      * <code>#getSharedWorkingCopy</code> should be used instead.
259      * </p><p>
260      * When the working copy instance is created, an ADDED IJavaElementDelta is
261      * reported on this working copy.
262      * </p><p>
263      * Since 2.1, a working copy can be created on a not-yet existing compilation
264      * unit. In particular, such a working copy can then be committed in order to create
265      * the corresponding compilation unit.
266      * </p>
267      * @param monitor a progress monitor used to report progress while opening this compilation unit
268      * or <code>null</code> if no progress should be reported
269      * @param factory the factory that creates a buffer that is used to get the content of the working copy
270      * or <code>null</code> if the internal factory should be used
271      * @param problemRequestor a requestor which will get notified of problems detected during
272      * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
273      * that the client is not interested in problems.
274      * @exception JavaModelException if the contents of this element can
275      * not be determined.
276      * @return a new working copy of this element using the given factory to create
277      * the buffer, or this element if this element is already a working copy
278      * @since 2.0
279      *
280      * @deprecated Use {@link ICompilationUnit#getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)} instead.
281      */
282     IJavaElement getWorkingCopy(
283         IProgressMonitor monitor,
284         IBufferFactory factory,
285         IProblemRequestor problemRequestor)
286         throws JavaModelException;
287         
288     /**
289      * Returns whether this working copy's original element's content
290      * has not changed since the inception of this working copy.
291      *
292      * @param resource this working copy's resource
293      * @return true if this working copy's original element's content
294      * has not changed since the inception of this working copy, false otherwise
295      *
296      * @deprecated Use {@link ICompilationUnit#hasResourceChanged()} instead.
297      */
298     boolean isBasedOn(IResource resource);
299     
300     /**
301      * Returns whether this element is a working copy.
302      *
303      * @return true if this element is a working copy, false otherwise
304      *
305      * @deprecated Use {@link ICompilationUnit#isWorkingCopy()} instead.
306      */
307     boolean isWorkingCopy();
308     
309     /**
310      * Reconciles the contents of this working copy.
311      * It performs the reconciliation by locally caching the contents of
312      * the working copy, updating the contents, then creating a delta
313      * over the cached contents and the new contents, and finally firing
314      * this delta.
315      * <p>
316      * If the working copy hasn't changed, then no problem will be detected,
317      * this is equivalent to <code>IWorkingCopy#reconcile(false, null)</code>.</p>
318      * <p>
319      * Compilation problems found in the new contents are notified through the
320      * <code>IProblemRequestor</code> interface which was passed at
321      * creation, and no longer as transient markers. Therefore this API will
322      * return <code>null</code>.</p>
323      * <p>
324      * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
325      *
326      * @exception JavaModelException if the contents of the original element
327      * cannot be accessed. Reasons include:
328      * <ul>
329      * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
330      * </ul>
331      * @return <code>null</code>
332      *
333      * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
334      */
335     IMarker[] reconcile() throws JavaModelException;
336     
337     /**
338      * Reconciles the contents of this working copy.
339      * It performs the reconciliation by locally caching the contents of
340      * the working copy, updating the contents, then creating a delta
341      * over the cached contents and the new contents, and finally firing
342      * this delta.
343      * <p>
344      * The boolean argument allows to force problem detection even if the
345      * working copy is already consistent.</p>
346      * <p>
347      * Compilation problems found in the new contents are notified through the
348      * <code>IProblemRequestor</code> interface which was passed at
349      * creation, and no longer as transient markers. Therefore this API answers
350      * nothing.</p>
351      * <p>
352      * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
353      *
354      * @param forceProblemDetection boolean indicating whether problem should be recomputed
355      * even if the source hasn't changed.
356      * @param monitor a progress monitor
357      * @exception JavaModelException if the contents of the original element
358      * cannot be accessed. Reasons include:
359      * <ul>
360      * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
361      * </ul>
362      * @since 2.0
363      *
364      * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
365      */
366     void reconcile(boolean forceProblemDetection, IProgressMonitor monitor) throws JavaModelException;
367
368     /**
369      * Restores the contents of this working copy to the current contents of
370      * this working copy's original element. Has no effect if this element
371      * is not a working copy.
372      *
373      * <p>Note: This is the inverse of committing the content of the
374      * working copy to the original element with <code>commit(boolean, IProgressMonitor)</code>.
375      *
376      * @exception JavaModelException if the contents of the original element
377      * cannot be accessed. Reasons include:
378      * <ul>
379      * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
380      * </ul>
381      * @deprecated Use {@link ICompilationUnit#restore()} instead.
382      */
383     void restore() throws JavaModelException;
384 }
385
Popular Tags