001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 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: * IBM Corporation - added J2SE 1.5 support
011: *******************************************************************************/package org.eclipse.jdt.core;
012:
013: import org.eclipse.core.runtime.IProgressMonitor;
014: import org.eclipse.jdt.core.dom.ASTParser;
015: import org.eclipse.jdt.core.dom.CompilationUnit;
016: import org.eclipse.jdt.core.dom.AST;
017: import org.eclipse.jdt.core.dom.IBinding;
018:
019: /**
020: * Represents an entire Java compilation unit (source file with one of the
021: * {@link JavaCore#getJavaLikeExtensions() Java-like extensions}).
022: * Compilation unit elements need to be opened before they can be navigated or manipulated.
023: * The children are of type {@link IPackageDeclaration},
024: * {@link IImportContainer}, and {@link IType},
025: * and appear in the order in which they are declared in the source.
026: * If a source file cannot be parsed, its structure remains unknown.
027: * Use {@link IJavaElement#isStructureKnown} to determine whether this is
028: * the case.
029: * <p>
030: * This interface is not intended to be implemented by clients.
031: * </p>
032: */
033: public interface ICompilationUnit extends ITypeRoot, IWorkingCopy,
034: ISourceManipulation {
035: /**
036: * Constant indicating that a reconcile operation should not return an AST.
037: * @since 3.0
038: */
039: public static final int NO_AST = 0;
040:
041: /**
042: * Constant indicating that a reconcile operation should recompute the problems
043: * even if the source hasn't changed.
044: * @since 3.3
045: */
046: public static final int FORCE_PROBLEM_DETECTION = 0x01;
047:
048: /**
049: * Constant indicating that a reconcile operation should enable the statements recovery.
050: * @see ASTParser#setStatementsRecovery(boolean)
051: * @since 3.3
052: */
053: public static final int ENABLE_STATEMENTS_RECOVERY = 0x02;
054:
055: /**
056: * Constant indicating that a reconcile operation should enable the bindings recovery
057: * @see ASTParser#setBindingsRecovery(boolean)
058: * @see IBinding#isRecovered()
059: * @since 3.3
060: */
061: public static final int ENABLE_BINDINGS_RECOVERY = 0x04;
062:
063: /**
064: * Changes this compilation unit handle into a working copy. A new {@link IBuffer} is
065: * created using this compilation unit handle's owner. Uses the primary owner if none was
066: * specified when this compilation unit handle was created.
067: * <p>
068: * When switching to working copy mode, problems are reported to given
069: * {@link IProblemRequestor}. Note that once in working copy mode, the given
070: * {@link IProblemRequestor} is ignored. Only the original {@link IProblemRequestor}
071: * is used to report subsequent problems.
072: * </p>
073: * <p>
074: * Once in working copy mode, changes to this compilation unit or its children are done in memory.
075: * Only the new buffer is affected. Using {@link #commitWorkingCopy(boolean, IProgressMonitor)}
076: * will bring the underlying resource in sync with this compilation unit.
077: * </p>
078: * <p>
079: * If this compilation unit was already in working copy mode, an internal counter is incremented and no
080: * other action is taken on this compilation unit. To bring this compilation unit back into the original mode
081: * (where it reflects the underlying resource), {@link #discardWorkingCopy} must be call as many
082: * times as {@link #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)}.
083: * </p>
084: *
085: * @param problemRequestor a requestor which will get notified of problems detected during
086: * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
087: * that the client is not interested in problems.
088: * @param monitor a progress monitor used to report progress while opening this compilation unit
089: * or <code>null</code> if no progress should be reported
090: * @throws JavaModelException if this compilation unit could not become a working copy.
091: * @see #discardWorkingCopy()
092: * @since 3.0
093: *
094: * @deprecated Use {@link #becomeWorkingCopy(IProgressMonitor)} instead.
095: * Note that if this deprecated method is used, problems will be reported to the given problem requestor
096: * as well as the problem requestor returned by the working copy owner (if not null).
097: */
098: void becomeWorkingCopy(IProblemRequestor problemRequestor,
099: IProgressMonitor monitor) throws JavaModelException;
100:
101: /**
102: * Changes this compilation unit handle into a working copy. A new {@link IBuffer} is
103: * created using this compilation unit handle's owner. Uses the primary owner if none was
104: * specified when this compilation unit handle was created.
105: * <p>
106: * When switching to working copy mode, problems are reported to the {@link IProblemRequestor
107: * problem requestor} of the {@link WorkingCopyOwner working copy owner}.
108: * </p><p>
109: * Once in working copy mode, changes to this compilation unit or its children are done in memory.
110: * Only the new buffer is affected. Using {@link #commitWorkingCopy(boolean, IProgressMonitor)}
111: * will bring the underlying resource in sync with this compilation unit.
112: * </p><p>
113: * If this compilation unit was already in working copy mode, an internal counter is incremented and no
114: * other action is taken on this compilation unit. To bring this compilation unit back into the original mode
115: * (where it reflects the underlying resource), {@link #discardWorkingCopy} must be call as many
116: * times as {@link #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)}.
117: * </p>
118: *
119: * @param monitor a progress monitor used to report progress while opening this compilation unit
120: * or <code>null</code> if no progress should be reported
121: * @throws JavaModelException if this compilation unit could not become a working copy.
122: * @see #discardWorkingCopy()
123: * @since 3.3
124: */
125: void becomeWorkingCopy(IProgressMonitor monitor)
126: throws JavaModelException;
127:
128: /**
129: * Commits the contents of this working copy to its underlying resource.
130: *
131: * <p>It is possible that the contents of the original resource have changed
132: * since this working copy was created, in which case there is an update conflict.
133: * The value of the <code>force</code> parameter effects the resolution of
134: * such a conflict:<ul>
135: * <li> <code>true</code> - in this case the contents of this working copy are applied to
136: * the underlying resource even though this working copy was created before
137: * a subsequent change in the resource</li>
138: * <li> <code>false</code> - in this case a {@link JavaModelException} is thrown</li>
139: * </ul>
140: * <p>
141: * Since 2.1, a working copy can be created on a not-yet existing compilation
142: * unit. In particular, such a working copy can then be committed in order to create
143: * the corresponding compilation unit.
144: * </p>
145: * @param force a flag to handle the cases when the contents of the original resource have changed
146: * since this working copy was created
147: * @param monitor the given progress monitor
148: * @throws JavaModelException if this working copy could not commit. Reasons include:
149: * <ul>
150: * <li> A {@link org.eclipse.core.runtime.CoreException} occurred while updating an underlying resource
151: * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
152: * <li> A update conflict (described above) (UPDATE_CONFLICT)
153: * </ul>
154: * @since 3.0
155: */
156: void commitWorkingCopy(boolean force, IProgressMonitor monitor)
157: throws JavaModelException;
158:
159: /**
160: * Creates and returns an non-static import declaration in this compilation unit
161: * with the given name. This method is equivalent to
162: * <code>createImport(name, Flags.AccDefault, sibling, monitor)</code>.
163: *
164: * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> or
165: * <code>"java.awt.*"</code>)
166: * @param sibling the existing element which the import declaration will be inserted immediately before (if
167: * <code> null </code>, then this import will be inserted as the last import declaration.
168: * @param monitor the progress monitor to notify
169: * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)
170: *
171: * @throws JavaModelException if the element could not be created. Reasons include:
172: * <ul>
173: * <li> This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
174: * <li> A {@link org.eclipse.core.runtime.CoreException} occurred while updating an underlying resource
175: * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
176: * <li> The name is not a valid import name (INVALID_NAME)
177: * </ul>
178: * @see #createImport(String, IJavaElement, int, IProgressMonitor)
179: */
180: IImportDeclaration createImport(String name, IJavaElement sibling,
181: IProgressMonitor monitor) throws JavaModelException;
182:
183: /**
184: * Creates and returns an import declaration in this compilation unit
185: * with the given name.
186: * <p>
187: * Optionally, the new element can be positioned before the specified
188: * sibling. If no sibling is specified, the element will be inserted
189: * as the last import declaration in this compilation unit.
190: * <p>
191: * If the compilation unit already includes the specified import declaration,
192: * the import is not generated (it does not generate duplicates).
193: * Note that it is valid to specify both a single-type import and an on-demand import
194: * for the same package, for example <code>"java.io.File"</code> and
195: * <code>"java.io.*"</code>, in which case both are preserved since the semantics
196: * of this are not the same as just importing <code>"java.io.*"</code>.
197: * Importing <code>"java.lang.*"</code>, or the package in which the compilation unit
198: * is defined, are not treated as special cases. If they are specified, they are
199: * included in the result.
200: * <p>
201: * Note: This API element is only needed for dealing with Java code that uses
202: * new language features of J2SE 5.0.
203: * </p>
204: *
205: * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> or
206: * <code>"java.awt.*"</code>)
207: * @param sibling the existing element which the import declaration will be inserted immediately before (if
208: * <code> null </code>, then this import will be inserted as the last import declaration.
209: * @param flags {@link Flags#AccStatic} for static imports, or
210: * {@link Flags#AccDefault} for regular imports; other modifier flags
211: * are ignored
212: * @param monitor the progress monitor to notify
213: * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)
214: *
215: * @throws JavaModelException if the element could not be created. Reasons include:
216: * <ul>
217: * <li> This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
218: * <li> A {@link org.eclipse.core.runtime.CoreException} occurred while updating an underlying resource
219: * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
220: * <li> The name is not a valid import name (INVALID_NAME)
221: * </ul>
222: * @see Flags
223: * @since 3.0
224: */
225: IImportDeclaration createImport(String name, IJavaElement sibling,
226: int flags, IProgressMonitor monitor)
227: throws JavaModelException;
228:
229: /**
230: * Creates and returns a package declaration in this compilation unit
231: * with the given package name.
232: *
233: * <p>If the compilation unit already includes the specified package declaration,
234: * it is not generated (it does not generate duplicates).
235: *
236: * @param name the name of the package declaration to add as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
237: * @param monitor the progress monitor to notify
238: * @return the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate)
239: *
240: * @throws JavaModelException if the element could not be created. Reasons include:
241: * <ul>
242: * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
243: * <li> A {@link org.eclipse.core.runtime.CoreException} occurred while updating an underlying resource
244: * <li> The name is not a valid package name (INVALID_NAME)
245: * </ul>
246: */
247: IPackageDeclaration createPackageDeclaration(String name,
248: IProgressMonitor monitor) throws JavaModelException;
249:
250: /**
251: * Creates and returns a type in this compilation unit with the
252: * given contents. If this compilation unit does not exist, one
253: * will be created with an appropriate package declaration.
254: * <p>
255: * Optionally, the new type can be positioned before the specified
256: * sibling. If <code>sibling</code> is <code>null</code>, the type will be appended
257: * to the end of this compilation unit.
258: *
259: * <p>It is possible that a type with the same name already exists in this compilation unit.
260: * The value of the <code>force</code> parameter effects the resolution of
261: * such a conflict:<ul>
262: * <li> <code>true</code> - in this case the type is created with the new contents</li>
263: * <li> <code>false</code> - in this case a {@link JavaModelException} is thrown</li>
264: * </ul>
265: *
266: * @param contents the source contents of the type declaration to add.
267: * @param sibling the existing element which the type will be inserted immediately before (if
268: * <code>null</code>, then this type will be inserted as the last type declaration.
269: * @param force a <code>boolean</code> flag indicating how to deal with duplicates
270: * @param monitor the progress monitor to notify
271: * @return the newly inserted type
272: *
273: * @throws JavaModelException if the element could not be created. Reasons include:
274: * <ul>
275: * <li>The specified sibling element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
276: * <li> A {@link org.eclipse.core.runtime.CoreException} occurred while updating an underlying resource
277: * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
278: * <li> The contents could not be recognized as a type declaration (INVALID_CONTENTS)
279: * <li> There was a naming collision with an existing type (NAME_COLLISION)
280: * </ul>
281: */
282: IType createType(String contents, IJavaElement sibling,
283: boolean force, IProgressMonitor monitor)
284: throws JavaModelException;
285:
286: /**
287: * Changes this compilation unit in working copy mode back to its original mode.
288: * <p>
289: * This has no effect if this compilation unit was not in working copy mode.
290: * </p>
291: * <p>
292: * If {@link #becomeWorkingCopy(IProgressMonitor)} method was called several
293: * times on this compilation unit, {@link #discardWorkingCopy()} must be called
294: * as many times before it switches back to the original mode. Same as
295: * for method {@link #getWorkingCopy(IProgressMonitor)}.
296: * </p>
297: *
298: * @throws JavaModelException if this working copy could not return in its original mode.
299: * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
300: * @since 3.0
301: */
302: void discardWorkingCopy() throws JavaModelException;
303:
304: /**
305: * Finds the elements in this compilation unit that correspond to
306: * the given element.
307: * An element A corresponds to an element B if:
308: * <ul>
309: * <li>A has the same element name as B.
310: * <li>If A is a method, A must have the same number of arguments as
311: * B and the simple names of the argument types must be equals.
312: * <li>The parent of A corresponds to the parent of B recursively up to
313: * their respective compilation units.
314: * <li>A exists.
315: * </ul>
316: * Returns <code>null</code> if no such java elements can be found
317: * or if the given element is not included in a compilation unit.
318: *
319: * @param element the given element
320: * @return the found elements in this compilation unit that correspond to the given element
321: * @since 3.0
322: */
323: IJavaElement[] findElements(IJavaElement element);
324:
325: /**
326: * Finds the working copy for this compilation unit, given a {@link WorkingCopyOwner}.
327: * If no working copy has been created for this compilation unit associated with this
328: * working copy owner, returns <code>null</code>.
329: * <p>
330: * Users of this method must not destroy the resulting working copy.
331: *
332: * @param owner the given {@link WorkingCopyOwner}
333: * @return the found working copy for this compilation unit, <code>null</code> if none
334: * @see WorkingCopyOwner
335: * @since 3.0
336: */
337: ICompilationUnit findWorkingCopy(WorkingCopyOwner owner);
338:
339: /**
340: * Returns all types declared in this compilation unit in the order
341: * in which they appear in the source.
342: * This includes all top-level types and nested member types.
343: * It does NOT include local types (types defined in methods).
344: *
345: * @return the array of top-level and member types defined in a compilation unit, in declaration order.
346: * @throws JavaModelException if this element does not exist or if an
347: * exception occurs while accessing its corresponding resource
348: */
349: IType[] getAllTypes() throws JavaModelException;
350:
351: /**
352: * Returns the first import declaration in this compilation unit with the given name.
353: * This is a handle-only method. The import declaration may or may not exist. This
354: * is a convenience method - imports can also be accessed from a compilation unit's
355: * import container.
356: *
357: * @param name the name of the import to find as defined by JLS2 7.5. (For example: <code>"java.io.File"</code>
358: * or <code>"java.awt.*"</code>)
359: * @return a handle onto the corresponding import declaration. The import declaration may or may not exist.
360: */
361: IImportDeclaration getImport(String name);
362:
363: /**
364: * Returns the import container for this compilation unit.
365: * This is a handle-only method. The import container may or
366: * may not exist. The import container can used to access the
367: * imports.
368: * @return a handle onto the corresponding import container. The
369: * import contain may or may not exist.
370: */
371: IImportContainer getImportContainer();
372:
373: /**
374: * Returns the import declarations in this compilation unit
375: * in the order in which they appear in the source. This is
376: * a convenience method - import declarations can also be
377: * accessed from a compilation unit's import container.
378: *
379: * @return the import declarations in this compilation unit
380: * @throws JavaModelException if this element does not exist or if an
381: * exception occurs while accessing its corresponding resource
382: */
383: IImportDeclaration[] getImports() throws JavaModelException;
384:
385: /**
386: * Returns the primary compilation unit (whose owner is the primary owner)
387: * this working copy was created from, or this compilation unit if this a primary
388: * compilation unit.
389: * <p>
390: * Note that the returned primary compilation unit can be in working copy mode.
391: * </p>
392: *
393: * @return the primary compilation unit this working copy was created from,
394: * or this compilation unit if it is primary
395: * @since 3.0
396: */
397: ICompilationUnit getPrimary();
398:
399: /**
400: * Returns the working copy owner of this working copy.
401: * Returns null if it is not a working copy or if it has no owner.
402: *
403: * @return WorkingCopyOwner the owner of this working copy or <code>null</code>
404: * @since 3.0
405: */
406: WorkingCopyOwner getOwner();
407:
408: /**
409: * Returns the first package declaration in this compilation unit with the given package name
410: * (there normally is at most one package declaration).
411: * This is a handle-only method. The package declaration may or may not exist.
412: *
413: * @param name the name of the package declaration as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
414: * @return the first package declaration in this compilation unit with the given package name
415: */
416: IPackageDeclaration getPackageDeclaration(String name);
417:
418: /**
419: * Returns the package declarations in this compilation unit
420: * in the order in which they appear in the source.
421: * There normally is at most one package declaration.
422: *
423: * @return an array of package declaration (normally of size one)
424: *
425: * @throws JavaModelException if this element does not exist or if an
426: * exception occurs while accessing its corresponding resource
427: */
428: IPackageDeclaration[] getPackageDeclarations()
429: throws JavaModelException;
430:
431: /**
432: * Returns the top-level type declared in this compilation unit with the given simple type name.
433: * The type name has to be a valid compilation unit name.
434: * This is a handle-only method. The type may or may not exist.
435: *
436: * @param name the simple name of the requested type in the compilation unit
437: * @return a handle onto the corresponding type. The type may or may not exist.
438: * @see JavaConventions#validateCompilationUnitName(String name, String sourceLevel, String complianceLevel)
439: */
440: IType getType(String name);
441:
442: /**
443: * Returns the top-level types declared in this compilation unit
444: * in the order in which they appear in the source.
445: *
446: * @return the top-level types declared in this compilation unit
447: * @throws JavaModelException if this element does not exist or if an
448: * exception occurs while accessing its corresponding resource
449: */
450: IType[] getTypes() throws JavaModelException;
451:
452: /**
453: * Returns a new working copy of this compilation unit if it is a primary compilation unit,
454: * or this compilation unit if it is already a non-primary working copy.
455: * <p>
456: * Note: if intending to share a working copy amongst several clients, then
457: * {@link #getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)}
458: * should be used instead.
459: * </p><p>
460: * When the working copy instance is created, an ADDED IJavaElementDelta is
461: * reported on this working copy.
462: * </p><p>
463: * Once done with the working copy, users of this method must discard it using
464: * {@link #discardWorkingCopy()}.
465: * </p><p>
466: * Since 2.1, a working copy can be created on a not-yet existing compilation
467: * unit. In particular, such a working copy can then be committed in order to create
468: * the corresponding compilation unit.
469: * </p>
470: * @param monitor a progress monitor used to report progress while opening this compilation unit
471: * or <code>null</code> if no progress should be reported
472: * @throws JavaModelException if the contents of this element can
473: * not be determined.
474: * @return a new working copy of this element if this element is not
475: * a working copy, or this element if this element is already a working copy
476: * @since 3.0
477: */
478: ICompilationUnit getWorkingCopy(IProgressMonitor monitor)
479: throws JavaModelException;
480:
481: /**
482: * Returns a shared working copy on this compilation unit using the given working copy owner to create
483: * the buffer, or this compilation unit if it is already a non-primary working copy.
484: * This API can only answer an already existing working copy if it is based on the same
485: * original compilation unit AND was using the same working copy owner (that is, as defined by {@link Object#equals}).
486: * <p>
487: * The life time of a shared working copy is as follows:
488: * <ul>
489: * <li>The first call to {@link #getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)}
490: * creates a new working copy for this element</li>
491: * <li>Subsequent calls increment an internal counter.</li>
492: * <li>A call to {@link #discardWorkingCopy()} decrements the internal counter.</li>
493: * <li>When this counter is 0, the working copy is discarded.
494: * </ul>
495: * So users of this method must discard exactly once the working copy.
496: * <p>
497: * Note that the working copy owner will be used for the life time of this working copy, that is if the
498: * working copy is closed then reopened, this owner will be used.
499: * The buffer will be automatically initialized with the original's compilation unit content
500: * upon creation.
501: * <p>
502: * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
503: * working copy.
504: * </p><p>
505: * Since 2.1, a working copy can be created on a not-yet existing compilation
506: * unit. In particular, such a working copy can then be committed in order to create
507: * the corresponding compilation unit.
508: * </p>
509: * @param owner the working copy owner that creates a buffer that is used to get the content
510: * of the working copy
511: * @param problemRequestor a requestor which will get notified of problems detected during
512: * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
513: * that the client is not interested in problems.
514: * @param monitor a progress monitor used to report progress while opening this compilation unit
515: * or <code>null</code> if no progress should be reported
516: * @throws JavaModelException if the contents of this element can
517: * not be determined.
518: * @return a new working copy of this element using the given factory to create
519: * the buffer, or this element if this element is already a working copy
520: * @since 3.0
521: * @deprecated Use {@link ITypeRoot#getWorkingCopy(WorkingCopyOwner, IProgressMonitor)} instead.
522: * Note that if this deprecated method is used, problems will be reported on the passed problem requester
523: * as well as on the problem requestor returned by the working copy owner (if not null).
524: */
525: ICompilationUnit getWorkingCopy(WorkingCopyOwner owner,
526: IProblemRequestor problemRequestor, IProgressMonitor monitor)
527: throws JavaModelException;
528:
529: /**
530: * Returns whether the resource of this working copy has changed since the
531: * inception of this working copy.
532: * Returns <code>false</code> if this compilation unit is not in working copy mode.
533: *
534: * @return whether the resource has changed
535: * @since 3.0
536: */
537: public boolean hasResourceChanged();
538:
539: /**
540: * Returns whether this element is a working copy.
541: *
542: * @return true if this element is a working copy, false otherwise
543: * @since 3.0
544: */
545: boolean isWorkingCopy();
546:
547: /**
548: * Reconciles the contents of this working copy, sends out a Java delta
549: * notification indicating the nature of the change of the working copy since
550: * the last time it was either reconciled or made consistent
551: * ({@link IOpenable#makeConsistent(IProgressMonitor)}), and returns a
552: * compilation unit AST if requested.
553: * <p>
554: * It performs the reconciliation by locally caching the contents of
555: * the working copy, updating the contents, then creating a delta
556: * over the cached contents and the new contents, and finally firing
557: * this delta.
558: * <p>
559: * The boolean argument allows to force problem detection even if the
560: * working copy is already consistent.
561: * </p>
562: * <p>
563: * This functionality allows to specify a working copy owner which is used
564: * during problem detection. All references contained in the working copy are
565: * resolved against other units; for which corresponding owned working copies
566: * are going to take precedence over their original compilation units. If
567: * <code>null</code> is passed in, then the primary working copy owner is used.
568: * </p>
569: * <p>
570: * Compilation problems found in the new contents are notified through the
571: * {@link IProblemRequestor} interface which was passed at
572: * creation, and no longer as transient markers.
573: * </p>
574: * <p>
575: * Note: Since 3.0, added/removed/changed inner types generate change deltas.
576: * </p>
577: * <p>
578: * If requested, a DOM AST representing the compilation unit is returned.
579: * Its bindings are computed only if the problem requestor is active, or if the
580: * problem detection is forced. This method returns <code>null</code> if the
581: * creation of the DOM AST was not requested, or if the requested level of AST
582: * API is not supported, or if the working copy was already consistent.
583: * </p>
584: *
585: * <p>
586: * This method doesn't perform statements recovery. To recover statements with syntax
587: * errors, {@link #reconcile(int, boolean, boolean, WorkingCopyOwner, IProgressMonitor)} must be use.
588: * </p>
589: *
590: * @param astLevel either {@link #NO_AST} if no AST is wanted,
591: * or the {@linkplain AST#newAST(int) AST API level} of the AST if one is wanted
592: * @param forceProblemDetection boolean indicating whether problem should be
593: * recomputed even if the source hasn't changed
594: * @param owner the owner of working copies that take precedence over the
595: * original compilation units, or <code>null</code> if the primary working
596: * copy owner should be used
597: * @param monitor a progress monitor
598: * @return the compilation unit AST or <code>null</code> if not requested,
599: * or if the requested level of AST API is not supported,
600: * or if the working copy was consistent
601: * @throws JavaModelException if the contents of the original element
602: * cannot be accessed. Reasons include:
603: * <ul>
604: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
605: * </ul>
606: * @since 3.0
607: */
608: CompilationUnit reconcile(int astLevel,
609: boolean forceProblemDetection, WorkingCopyOwner owner,
610: IProgressMonitor monitor) throws JavaModelException;
611:
612: /**
613: * Reconciles the contents of this working copy, sends out a Java delta
614: * notification indicating the nature of the change of the working copy since
615: * the last time it was either reconciled or made consistent
616: * ({@link IOpenable#makeConsistent(IProgressMonitor)}), and returns a
617: * compilation unit AST if requested.
618: * <p>
619: * It performs the reconciliation by locally caching the contents of
620: * the working copy, updating the contents, then creating a delta
621: * over the cached contents and the new contents, and finally firing
622: * this delta.
623: * <p>
624: * The boolean argument allows to force problem detection even if the
625: * working copy is already consistent.
626: * </p>
627: * <p>
628: * This functionality allows to specify a working copy owner which is used
629: * during problem detection. All references contained in the working copy are
630: * resolved against other units; for which corresponding owned working copies
631: * are going to take precedence over their original compilation units. If
632: * <code>null</code> is passed in, then the primary working copy owner is used.
633: * </p>
634: * <p>
635: * Compilation problems found in the new contents are notified through the
636: * {@link IProblemRequestor} interface which was passed at
637: * creation, and no longer as transient markers.
638: * </p>
639: * <p>
640: * Note: Since 3.0, added/removed/changed inner types generate change deltas.
641: * </p>
642: * <p>
643: * If requested, a DOM AST representing the compilation unit is returned.
644: * Its bindings are computed only if the problem requestor is active, or if the
645: * problem detection is forced. This method returns <code>null</code> if the
646: * creation of the DOM AST was not requested, or if the requested level of AST
647: * API is not supported, or if the working copy was already consistent.
648: * </p>
649: *
650: * <p>
651: * If statements recovery is enabled then this method tries to rebuild statements
652: * with syntax error. Otherwise statements with syntax error won't be present in
653: * the returning DOM AST.
654: * </p>
655: *
656: * @param astLevel either {@link #NO_AST} if no AST is wanted,
657: * or the {@linkplain AST#newAST(int) AST API level} of the AST if one is wanted
658: * @param forceProblemDetection boolean indicating whether problem should be
659: * recomputed even if the source hasn't changed
660: * @param enableStatementsRecovery if <code>true</code> statements recovery is enabled.
661: * @param owner the owner of working copies that take precedence over the
662: * original compilation units, or <code>null</code> if the primary working
663: * copy owner should be used
664: * @param monitor a progress monitor
665: * @return the compilation unit AST or <code>null</code> if not requested,
666: * or if the requested level of AST API is not supported,
667: * or if the working copy was consistent
668: * @throws JavaModelException if the contents of the original element
669: * cannot be accessed. Reasons include:
670: * <ul>
671: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
672: * </ul>
673: * @since 3.2
674: */
675: CompilationUnit reconcile(int astLevel,
676: boolean forceProblemDetection,
677: boolean enableStatementsRecovery, WorkingCopyOwner owner,
678: IProgressMonitor monitor) throws JavaModelException;
679:
680: /**
681: * Reconciles the contents of this working copy, sends out a Java delta
682: * notification indicating the nature of the change of the working copy since
683: * the last time it was either reconciled or made consistent
684: * ({@link IOpenable#makeConsistent(IProgressMonitor)}), and returns a
685: * compilation unit AST if requested.
686: *
687: * <p>
688: * If the problem detection is forced by passing the {@link #FORCE_PROBLEM_DETECTION} bit in the given reconcile flag,
689: * problem detection is run even if the working copy is already consistent.
690: * </p>
691: *
692: * <p>
693: * It performs the reconciliation by locally caching the contents of
694: * the working copy, updating the contents, then creating a delta
695: * over the cached contents and the new contents, and finally firing
696: * this delta.</p>
697: *
698: * <p>
699: * This functionality allows to specify a working copy owner which is used
700: * during problem detection. All references contained in the working copy are
701: * resolved against other units; for which corresponding owned working copies
702: * are going to take precedence over their original compilation units. If
703: * <code>null</code> is passed in, then the primary working copy owner is used.
704: * </p>
705: * <p>
706: * Compilation problems found in the new contents are notified through the
707: * {@link IProblemRequestor} interface which was passed at
708: * creation, and no longer as transient markers.
709: * </p>
710: * <p>
711: * Note: Since 3.0, added/removed/changed inner types generate change deltas.
712: * </p>
713: * <p>
714: * If requested, a DOM AST representing the compilation unit is returned.
715: * Its bindings are computed only if the problem requestor is active, or if the
716: * problem detection is forced. This method returns <code>null</code> if the
717: * creation of the DOM AST was not requested, or if the requested level of AST
718: * API is not supported, or if the working copy was already consistent.
719: * </p>
720: *
721: * <p>
722: * If statements recovery is enabled by passing the {@link #ENABLE_STATEMENTS_RECOVERY} bit in the given reconcile flag
723: * then this method tries to rebuild statements with syntax error. Otherwise statements with syntax error won't be
724: * present in the returning DOM AST.</p>
725: * <p>
726: * If bindings recovery is enabled by passing the {@link #ENABLE_BINDINGS_RECOVERY} bit in the given reconcile flag
727: * then this method tries to resolve bindings even if the type resolution contains errors.</p>
728: * <p>
729: * The given reconcile flags is a bit-mask of the different constants ({@link #ENABLE_BINDINGS_RECOVERY},
730: * {@link #ENABLE_STATEMENTS_RECOVERY}, {@link #FORCE_PROBLEM_DETECTION}). Unspecified values are left for future use.
731: * </p>
732: *
733: * @param astLevel either {@link #NO_AST} if no AST is wanted,
734: * or the {@linkplain AST#newAST(int) AST API level} of the AST if one is wanted
735: * @param reconcileFlags the given reconcile flags
736: * @param owner the owner of working copies that take precedence over the
737: * original compilation units, or <code>null</code> if the primary working
738: * copy owner should be used
739: * @param monitor a progress monitor
740: * @return the compilation unit AST or <code>null</code> if not requested,
741: * or if the requested level of AST API is not supported,
742: * or if the working copy was consistent
743: * @throws JavaModelException if the contents of the original element
744: * cannot be accessed. Reasons include:
745: * <ul>
746: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
747: * </ul>
748: * @see #FORCE_PROBLEM_DETECTION
749: * @see #ENABLE_BINDINGS_RECOVERY
750: * @see #ENABLE_STATEMENTS_RECOVERY
751: * @since 3.3
752: */
753: CompilationUnit reconcile(int astLevel, int reconcileFlags,
754: WorkingCopyOwner owner, IProgressMonitor monitor)
755: throws JavaModelException;
756:
757: /**
758: * Restores the contents of this working copy to the current contents of
759: * this working copy's original element. Has no effect if this element
760: * is not a working copy.
761: *
762: * <p>Note: This is the inverse of committing the content of the
763: * working copy to the original element with {@link #commitWorkingCopy(boolean, IProgressMonitor)}.
764: *
765: * @throws JavaModelException if the contents of the original element
766: * cannot be accessed. Reasons include:
767: * <ul>
768: * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
769: * </ul>
770: * @since 3.0
771: */
772: void restore() throws JavaModelException;
773: }
|