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