001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core;
011:
012: import org.eclipse.core.resources.IMarker;
013: import org.eclipse.core.resources.IResource;
014: import org.eclipse.core.runtime.IProgressMonitor;
015:
016: /**
017: * Common protocol for Java elements that support working copies.
018: * <p>
019: * A working copy of a Java element acts just like a regular element (handle),
020: * except it is not attached to an underlying resource. A working copy is not
021: * visible to the rest of the Java model. Changes in a working copy's
022: * buffer are not realized in a resource. To bring the Java model up-to-date with a working
023: * copy's contents, an explicit commit must be performed on the working copy.
024: * Other operations performed on a working copy update the
025: * contents of the working copy's buffer but do not commit the contents
026: * of the working copy.
027: * </p>
028: * <p>
029: * Note: The contents of a working copy is determined when a working
030: * copy is created, based on the current content of the element the working
031: * copy is created from. If a working copy is an <code>IOpenable</code> and is explicitly
032: * closed, the working copy's buffer will be thrown away. However, clients should not
033: * explicitly open and close working copies.
034: * </p>
035: * <p>
036: * The client that creates a working copy is responsible for
037: * destroying the working copy. The Java model will never automatically
038: * destroy or close a working copy. (Note that destroying a working copy
039: * does not commit it to the model, it only frees up the memory occupied by
040: * the element). After a working copy is destroyed, the working copy cannot
041: * be accessed again. Non-handle methods will throw a
042: * <code>JavaModelException</code> indicating the Java element does not exist.
043: * </p>
044: * <p>
045: * A working copy cannot be created from another working copy.
046: * Calling <code>getWorkingCopy</code> on a working copy returns the receiver.
047: * </p>
048: * <p>
049: * This interface is not intended to be implemented by clients.
050: * </p>
051: * @deprecated Use {@link ICompilationUnit} instead
052: */
053: public interface IWorkingCopy {
054:
055: /**
056: * Commits the contents of this working copy to its original element
057: * and underlying resource, bringing the Java model up-to-date with
058: * the current contents of the working copy.
059: *
060: * <p>It is possible that the contents of the original resource have changed
061: * since this working copy was created, in which case there is an update conflict.
062: * The value of the <code>force</code> parameter effects the resolution of
063: * such a conflict:<ul>
064: * <li> <code>true</code> - in this case the contents of this working copy are applied to
065: * the underlying resource even though this working copy was created before
066: * a subsequent change in the resource</li>
067: * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
068: * </ul>
069: * <p>
070: * Since 2.1, a working copy can be created on a not-yet existing compilation
071: * unit. In particular, such a working copy can then be committed in order to create
072: * the corresponding compilation unit.
073: * </p>
074: * @param force a flag to handle the cases when the contents of the original resource have changed
075: * since this working copy was created
076: * @param monitor the given progress monitor
077: * @exception JavaModelException if this working copy could not commit. Reasons include:
078: * <ul>
079: * <li> A <code>CoreException</code> occurred while updating an underlying resource
080: * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
081: * <li> A update conflict (described above) (UPDATE_CONFLICT)
082: * </ul>
083: * @deprecated Use {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} instead.
084: */
085: void commit(boolean force, IProgressMonitor monitor)
086: throws JavaModelException;
087:
088: /**
089: * Destroys this working copy, closing its buffer and discarding
090: * its structure. Subsequent attempts to access non-handle information
091: * for this working copy will result in <code>IJavaModelException</code>s. Has
092: * no effect if this element is not a working copy.
093: * <p>
094: * If this working copy is shared, it is destroyed only when the number of calls to
095: * <code>destroy()</code> is the same as the number of calls to <code>
096: * getSharedWorkingCopy(IProgressMonitor, IBufferFactory)</code>.
097: * </p><p>
098: * When it is destroyed, a REMOVED IJavaElementDelta is reported on this
099: * 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(IProgressMonitor monitor,
221: IBufferFactory factory, IProblemRequestor problemRequestor)
222: throws JavaModelException;
223:
224: /**
225: * Returns a new working copy of this element if this element is not
226: * a working copy, or this element if this element is already a working copy.
227: * <p>
228: * Note: if intending to share a working copy amongst several clients, then
229: * <code>#getSharedWorkingCopy</code> should be used instead.
230: * </p><p>
231: * When the working copy instance is created, an ADDED IJavaElementDelta is
232: * reported on this working copy.
233: * </p><p>
234: * Since 2.1, a working copy can be created on a not-yet existing compilation
235: * unit. In particular, such a working copy can then be committed in order to create
236: * the corresponding compilation unit.
237: * </p>
238: * @exception JavaModelException if the contents of this element can
239: * not be determined.
240: * @return a new working copy of this element if this element is not
241: * a working copy, or this element if this element is already a working copy
242: *
243: * @deprecated Use {@link ICompilationUnit#getWorkingCopy(IProgressMonitor)} instead.
244: */
245: IJavaElement getWorkingCopy() throws JavaModelException;
246:
247: /**
248: * Returns a new working copy of this element using the given factory to create
249: * the buffer, or this element if this element is already a working copy.
250: * Note that this factory will be used for the life time of this working copy, that is if the
251: * working copy is closed then reopened, this factory will be reused.
252: * The buffer will be automatically initialized with the original's compilation unit content
253: * upon creation.
254: * <p>
255: * Note: if intending to share a working copy amongst several clients, then
256: * <code>#getSharedWorkingCopy</code> should be used instead.
257: * </p><p>
258: * When the working copy instance is created, an ADDED IJavaElementDelta is
259: * reported on this working copy.
260: * </p><p>
261: * Since 2.1, a working copy can be created on a not-yet existing compilation
262: * unit. In particular, such a working copy can then be committed in order to create
263: * the corresponding compilation unit.
264: * </p>
265: * @param monitor a progress monitor used to report progress while opening this compilation unit
266: * or <code>null</code> if no progress should be reported
267: * @param factory the factory that creates a buffer that is used to get the content of the working copy
268: * or <code>null</code> if the internal factory should be used
269: * @param problemRequestor a requestor which will get notified of problems detected during
270: * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
271: * that the client is not interested in problems.
272: * @exception JavaModelException if the contents of this element can
273: * not be determined.
274: * @return a new working copy of this element using the given factory to create
275: * the buffer, or this element if this element is already a working copy
276: * @since 2.0
277: *
278: * @deprecated Use {@link ICompilationUnit#getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)} instead.
279: */
280: IJavaElement getWorkingCopy(IProgressMonitor monitor,
281: IBufferFactory factory, IProblemRequestor problemRequestor)
282: throws JavaModelException;
283:
284: /**
285: * Returns whether this working copy's original element's content
286: * has not changed since the inception of this working copy.
287: *
288: * @param resource this working copy's resource
289: * @return true if this working copy's original element's content
290: * has not changed since the inception of this working copy, false otherwise
291: *
292: * @deprecated Use {@link ICompilationUnit#hasResourceChanged()} instead.
293: */
294: boolean isBasedOn(IResource resource);
295:
296: /**
297: * Returns whether this element is a working copy.
298: *
299: * @return true if this element is a working copy, false otherwise
300: *
301: * @deprecated Use {@link ICompilationUnit#isWorkingCopy()} instead.
302: */
303: boolean isWorkingCopy();
304:
305: /**
306: * Reconciles the contents of this working copy.
307: * It performs the reconciliation by locally caching the contents of
308: * the working copy, updating the contents, then creating a delta
309: * over the cached contents and the new contents, and finally firing
310: * this delta.
311: * <p>
312: * If the working copy hasn't changed, then no problem will be detected,
313: * this is equivalent to <code>IWorkingCopy#reconcile(false, null)</code>.</p>
314: * <p>
315: * Compilation problems found in the new contents are notified through the
316: * <code>IProblemRequestor</code> interface which was passed at
317: * creation, and no longer as transient markers. Therefore this API will
318: * return <code>null</code>.</p>
319: * <p>
320: * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
321: *
322: * @exception JavaModelException if the contents of the original element
323: * cannot be accessed. Reasons include:
324: * <ul>
325: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
326: * </ul>
327: * @return <code>null</code>
328: *
329: * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
330: */
331: IMarker[] reconcile() throws JavaModelException;
332:
333: /**
334: * Reconciles the contents of this working copy.
335: * It performs the reconciliation by locally caching the contents of
336: * the working copy, updating the contents, then creating a delta
337: * over the cached contents and the new contents, and finally firing
338: * this delta.
339: * <p>
340: * The boolean argument allows to force problem detection even if the
341: * working copy is already consistent.</p>
342: * <p>
343: * Compilation problems found in the new contents are notified through the
344: * <code>IProblemRequestor</code> interface which was passed at
345: * creation, and no longer as transient markers. Therefore this API answers
346: * nothing.</p>
347: * <p>
348: * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
349: *
350: * @param forceProblemDetection boolean indicating whether problem should be recomputed
351: * even if the source hasn't changed.
352: * @param monitor a progress monitor
353: * @exception JavaModelException if the contents of the original element
354: * cannot be accessed. Reasons include:
355: * <ul>
356: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
357: * </ul>
358: * @since 2.0
359: *
360: * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
361: */
362: void reconcile(boolean forceProblemDetection,
363: IProgressMonitor monitor) throws JavaModelException;
364:
365: /**
366: * Restores the contents of this working copy to the current contents of
367: * this working copy's original element. Has no effect if this element
368: * is not a working copy.
369: *
370: * <p>Note: This is the inverse of committing the content of the
371: * working copy to the original element with <code>commit(boolean, IProgressMonitor)</code>.
372: *
373: * @exception JavaModelException if the contents of the original element
374: * cannot be accessed. Reasons include:
375: * <ul>
376: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
377: * </ul>
378: * @deprecated Use {@link ICompilationUnit#restore()} instead.
379: */
380: void restore() throws JavaModelException;
381: }
|