ICompilationUnit


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