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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.resources.IMarker;
14 import org.eclipse.core.resources.IResource;
15 import org.eclipse.core.runtime.IProgressMonitor;
18 * Common protocol for Java elements that support working copies.
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 buffer are
23 * 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 contents of the
26 * working copy's buffer but do not commit the contents of the working copy.
29 * Note: The contents of a working copy is determined when a working copy is
30 * created, based on the current content of the element the working copy is
31 * created from. If a working copy is an <code>IOpenable</code> and is
32 * explicitly closed, the working copy's buffer will be thrown away. However,
33 * clients should not explicitly open and close working copies.
36 * The client that creates a working copy is responsible for destroying the
37 * working copy. The Java model will never automatically destroy or close a
38 * working copy. (Note that destroying a working copy does not commit it to the
39 * model, it only frees up the memory occupied by the element). After a working
40 * copy is destroyed, the working copy cannot be accessed again. Non-handle
41 * methods will throw a <code>JavaModelException</code> indicating the Java
42 * element does not exist.
45 * A working copy cannot be created from another working copy. Calling
46 * <code>getWorkingCopy</code> on a working copy returns the receiver.
49 * This interface is not intended to be implemented by clients.
52 public interface IWorkingCopy {
55 * Commits the contents of this working copy to its original element and
56 * underlying resource, bringing the Java model up-to-date with the current
57 * contents of the working copy.
60 * 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
62 * conflict. The value of the <code>force</code> parameter effects the
63 * resolution of such a conflict:
65 * <li> <code>true</code> - in this case the contents of this working copy
66 * are applied to the underlying resource even though this working copy was
67 * created before a subsequent change in the resource</li>
68 * <li> <code>false</code> - in this case a
69 * <code>JavaModelException</code> is thrown</li>
72 * Since 2.1, a working copy can be created on a not-yet existing
73 * compilation unit. In particular, such a working copy can then be
74 * committed in order to create the corresponding compilation unit.
78 * a flag to handle the cases when the contents of the original
79 * resource have changed since this working copy was created
81 * the given progress monitor
82 * @exception JavaModelException
83 * if this working copy could not commit. Reasons include:
85 * <li> A <code>CoreException</code> occurred while
86 * updating an underlying resource
87 * <li> This element is not a working copy
88 * (INVALID_ELEMENT_TYPES)
89 * <li> A update conflict (described above) (UPDATE_CONFLICT)
92 void commit(boolean force, IProgressMonitor monitor)
93 throws JavaModelException;
96 * Destroys this working copy, closing its buffer and discarding its
97 * structure. Subsequent attempts to access non-handle information for this
98 * working copy will result in <code>IJavaModelException</code>s. Has no
99 * effect if this element is not a working copy.
101 * If this working copy is shared, it is destroyed only when the number of
102 * calls to <code>destroy()</code> is the same as the number of calls to
104 * getSharedWorkingCopy(IProgressMonitor, IBufferFactory)</code>.
107 * When it is destroyed, a REMOVED IJavaElementDelta is reported on this
114 * Finds the shared working copy for this element, given a
115 * <code>IBuffer</code> factory. If no working copy has been created for
116 * this element associated with this buffer factory, returns
119 * Users of this method must not destroy the resulting working copy.
121 * @param bufferFactory
122 * the given <code>IBuffer</code> factory
123 * @return the found shared working copy for this element, <code>null</code>
125 * @see IBufferFactory
128 IJavaElement findSharedWorkingCopy(IBufferFactory bufferFactory);
131 * Returns the original element the specified working copy element was
132 * created from, or <code>null</code> if this is not a working copy
133 * element. This is a handle only method, the returned element may or may
136 * @return the original element the specified working copy element was
137 * created from, or <code>null</code> if this is not a working
140 IJavaElement getOriginal(IJavaElement workingCopyElement);
143 * Returns the original element this working copy was created from, or
144 * <code>null</code> if this is not a working copy.
146 * @return the original element this working copy was created from, or
147 * <code>null</code> if this is not a working copy
149 IJavaElement getOriginalElement();
152 * Finds the elements in this compilation unit that correspond to the given
153 * element. An element A corresponds to an element B if:
155 * <li>A has the same element name as B.
156 * <li>If A is a method, A must have the same number of arguments as B and
157 * the simple names of the argument types must be equals.
158 * <li>The parent of A corresponds to the parent of B recursively up to
159 * their respective compilation units.
162 * Returns <code>null</code> if no such java elements can be found or if
163 * the given element is not included in a compilation unit.
167 * @return the found elements in this compilation unit that correspond to
171 IJavaElement[] findElements(IJavaElement element);
174 * Finds the primary type of this compilation unit (that is, the type with
175 * the same name as the compilation unit), or <code>null</code> if no such
178 * @return the found primary type of this compilation unit, or
179 * <code>null</code> if no such a type exists
182 IType findPrimaryType();
185 * Returns a shared working copy on this element using the given factory to
186 * create the buffer, or this element if this element is already a working
187 * copy. This API can only answer an already existing working copy if it is
188 * based on the same original compilation unit AND was using the same buffer
189 * factory (that is, as defined by <code>Object.equals</code>).
191 * The life time of a shared working copy is as follows:
193 * <li>The first call to <code>getSharedWorkingCopy(...)</code> creates a
194 * new working copy for this element</li>
195 * <li>Subsequent calls increment an internal counter.</li>
196 * <li>A call to <code>destroy()</code> decrements the internal counter.</li>
197 * <li>When this counter is 0, the working copy is destroyed.
199 * So users of this method must destroy exactly once the working copy.
201 * Note that the buffer factory will be used for the life time of this
202 * working copy, that is if the working copy is closed then reopened, this
203 * factory will be used. The buffer will be automatically initialized with
204 * the original's compilation unit content upon creation.
206 * When the shared working copy instance is created, an ADDED
207 * IJavaElementDelta is reported on this working copy.
210 * a progress monitor used to report progress while opening this
211 * compilation unit or <code>null</code> if no progress should
214 * the factory that creates a buffer that is used to get the
215 * content of the working copy or <code>null</code> if the
216 * internal factory should be used
217 * @param problemRequestor
218 * a requestor which will get notified of problems detected
219 * during reconciling as they are discovered. The requestor can
220 * be set to <code>null</code> indicating that the client is
221 * not interested in problems.
222 * @exception JavaModelException
223 * if the contents of this element can not be determined.
224 * @return a shared working copy on this element using the given factory to
225 * create the buffer, or this element if this element is already a
227 * @see IBufferFactory
228 * @see IProblemRequestor
231 IJavaElement getSharedWorkingCopy(IProgressMonitor monitor,
232 IBufferFactory factory, IProblemRequestor problemRequestor)
233 throws JavaModelException;
236 * Returns a new working copy of this element if this element is not a
237 * working copy, or this element if this element is already a working copy.
239 * Note: if intending to share a working copy amongst several clients, then
240 * <code>#getSharedWorkingCopy</code> should be used instead.
243 * When the working copy instance is created, an ADDED IJavaElementDelta is
244 * reported on this working copy.
247 * Since 2.1, a working copy can be created on a not-yet existing
248 * compilation unit. In particular, such a working copy can then be
249 * committed in order to create the corresponding compilation unit.
252 * @exception JavaModelException
253 * if the contents of this element can not be determined.
254 * @return a new working copy of this element if this element is not a
255 * working copy, or this element if this element is already a
258 IJavaElement getWorkingCopy() throws JavaModelException;
261 * Returns a new working copy of this element using the given factory to
262 * create the buffer, or this element if this element is already a working
263 * copy. Note that this factory will be used for the life time of this
264 * working copy, that is if the working copy is closed then reopened, this
265 * factory will be reused. The buffer will be automatically initialized with
266 * the original's compilation unit content upon creation.
268 * Note: if intending to share a working copy amongst several clients, then
269 * <code>#getSharedWorkingCopy</code> should be used instead.
272 * When the working copy instance is created, an ADDED IJavaElementDelta is
273 * reported on this working copy.
276 * Since 2.1, a working copy can be created on a not-yet existing
277 * compilation unit. In particular, such a working copy can then be
278 * committed in order to create the corresponding compilation unit.
282 * a progress monitor used to report progress while opening this
283 * compilation unit or <code>null</code> if no progress should
286 * the factory that creates a buffer that is used to get the
287 * content of the working copy or <code>null</code> if the
288 * internal factory should be used
289 * @param problemRequestor
290 * a requestor which will get notified of problems detected
291 * during reconciling as they are discovered. The requestor can
292 * be set to <code>null</code> indicating that the client is
293 * not interested in problems.
294 * @exception JavaModelException
295 * if the contents of this element can not be determined.
296 * @return a new working copy of this element using the given factory to
297 * create the buffer, or this element if this element is already a
301 IJavaElement getWorkingCopy(IProgressMonitor monitor,
302 IBufferFactory factory, IProblemRequestor problemRequestor)
303 throws JavaModelException;
306 * Returns whether this working copy's original element's content has not
307 * changed since the inception of this working copy.
309 * @return true if this working copy's original element's content has not
310 * changed since the inception of this working copy, false otherwise
312 boolean isBasedOn(IResource resource);
315 * Returns whether this element is a working copy.
317 * @return true if this element is a working copy, false otherwise
319 boolean isWorkingCopy();
322 * Reconciles the contents of this working copy. It performs the
323 * reconciliation by locally caching the contents of the working copy,
324 * updating the contents, then creating a delta over the cached contents and
325 * the new contents, and finally firing this delta.
327 * If the working copy hasn't changed, then no problem will be detected,
328 * this is equivalent to <code>IWorkingCopy#reconcile(false, null)</code>.
330 * Compilation problems found in the new contents are notified through the
331 * <code>IProblemRequestor</code> interface which was passed at creation,
332 * and no longer as transient markers. Therefore this API will return
335 * Note: It has been assumed that added inner types should not generate
336 * change deltas. The implementation has been modified to reflect this
339 * @exception JavaModelException
340 * if the contents of the original element cannot be
341 * accessed. Reasons include:
343 * <li> The original Java element does not exist
344 * (ELEMENT_DOES_NOT_EXIST)</li>
346 * @return <code>null</code>
348 IMarker[] reconcile() throws JavaModelException;
351 * Reconciles the contents of this working copy. It performs the
352 * reconciliation by locally caching the contents of the working copy,
353 * updating the contents, then creating a delta over the cached contents and
354 * the new contents, and finally firing this delta.
356 * The boolean argument allows to force problem detection even if the
357 * working copy is already consistent.
359 * Compilation problems found in the new contents are notified through the
360 * <code>IProblemRequestor</code> interface which was passed at creation,
361 * and no longer as transient markers. Therefore this API answers nothing.
363 * Note: It has been assumed that added inner types should not generate
364 * change deltas. The implementation has been modified to reflect this
367 * @param forceProblemDetection
368 * boolean indicating whether problem should be recomputed even
369 * if the source hasn't changed.
372 * @exception JavaModelException
373 * if the contents of the original element cannot be
374 * accessed. Reasons include:
376 * <li> The original Java element does not exist
377 * (ELEMENT_DOES_NOT_EXIST)</li>
381 void reconcile(boolean forceProblemDetection, IProgressMonitor monitor)
382 throws JavaModelException;
385 * Restores the contents of this working copy to the current contents of
386 * this working copy's original element. Has no effect if this element is
387 * not a working copy.
390 * Note: This is the inverse of committing the content of the working copy
391 * to the original element with
392 * <code>commit(boolean, IProgressMonitor)</code>.
394 * @exception JavaModelException
395 * if the contents of the original element cannot be
396 * accessed. Reasons include:
398 * <li> The original Java element does not exist
399 * (ELEMENT_DOES_NOT_EXIST)</li>
402 void restore() throws JavaModelException;