b00a4e5913c0503eda6c9f503c311f47b61c8eec
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / ICompilationUnit.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2003 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v10.html
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package net.sourceforge.phpdt.core;
12
13 import org.eclipse.core.runtime.IProgressMonitor;
14 import net.sourceforge.phpdt.core.IProblemRequestor;
15 import net.sourceforge.phpdt.core.JavaModelException;
16
17
18
19 /**
20  * Represents an entire Java compilation unit (<code>.java</code> source file).
21  * Compilation unit elements need to be opened before they can be navigated or manipulated.
22  * The children are of type <code>IPackageDeclaration</code>,
23  * <code>IImportContainer</code>, and <code>IType</code>,
24  * and appear in the order in which they are declared in the source.
25  * If a <code>.java</code> file cannot be parsed, its structure remains unknown.
26  * Use <code>IJavaElement.isStructureKnown</code> to determine whether this is 
27  * the case.
28  * <p>
29  * This interface is not intended to be implemented by clients.
30  * </p>
31  */ 
32 public interface ICompilationUnit extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation {
33 //extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist {
34
35         /**
36          * Constant indicating that a reconcile operation should not return an AST.
37          * @since 3.0
38          */
39         public static final int NO_AST = 0;
40
41         /**
42          * Changes this compilation unit handle into a working copy. A new <code>IBuffer</code> is
43          * created using this compilation unit handle's owner. Uses the primary owner is none was
44          * specified when this compilation unit handle was created.
45          * <p>
46          * When switching to working copy mode, problems are reported to given 
47          * <code>IProblemRequestor</code>.
48          * </p>
49          * <p>
50          * Once in working copy mode, changes to this compilation unit or its children are done in memory.
51          * Only the new buffer is affected. Using <code>commitWorkingCopy(boolean, IProgressMonitor)</code>
52          * will bring the underlying resource in sync with this compilation unit.
53          * </p>
54          * <p>
55          * If this compilation unit was already in working copy mode, an internal counter is incremented and no
56          * other action is taken on this compilation unit. To bring this compilation unit back into the original mode 
57          * (where it reflects the underlying resource), <code>discardWorkingCopy</code> must be call as many 
58          * times as <code>becomeWorkingCopy</code>.
59          * </p>
60          * 
61          * @param problemRequestor a requestor which will get notified of problems detected during
62          *      reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
63          *      that the client is not interested in problems.
64          * @param monitor a progress monitor used to report progress while opening this compilation unit
65          *      or <code>null</code> if no progress should be reported 
66          * @throws JavaModelException if this compilation unit could not become a working copy.
67          * @see #discardWorkingCopy()
68          * @since 3.0
69          */
70         void becomeWorkingCopy(IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException;
71         /**
72          * Commits the contents of this working copy to its underlying resource.
73          *
74          * <p>It is possible that the contents of the original resource have changed
75          * since this working copy was created, in which case there is an update conflict.
76          * The value of the <code>force</code> parameter effects the resolution of
77          * such a conflict:<ul>
78          * <li> <code>true</code> - in this case the contents of this working copy are applied to
79          *      the underlying resource even though this working copy was created before
80          *              a subsequent change in the resource</li>
81          * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
82          * </ul>
83          * <p>
84          * Since 2.1, a working copy can be created on a not-yet existing compilation
85          * unit. In particular, such a working copy can then be committed in order to create
86          * the corresponding compilation unit.
87          * </p>
88          * @param force a flag to handle the cases when the contents of the original resource have changed
89          * since this working copy was created
90          * @param monitor the given progress monitor
91          * @throws JavaModelException if this working copy could not commit. Reasons include:
92          * <ul>
93          * <li> A <code>CoreException</code> occurred while updating an underlying resource
94          * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
95          * <li> A update conflict (described above) (UPDATE_CONFLICT)
96          * </ul>
97          * @since 3.0
98          */
99         void commitWorkingCopy(boolean force, IProgressMonitor monitor) throws JavaModelException;
100         /**
101          * Changes this compilation unit in working copy mode back to its original mode.
102          * <p>
103          * This has no effect if this compilation unit was not in working copy mode.
104          * </p>
105          * <p>
106          * If <code>becomeWorkingCopy</code> was called several times on this
107          * compilation unit, <code>discardWorkingCopy</code> must be called as 
108          * many times before it switches back to the original mode.
109          * </p>
110          * 
111          * @throws JavaModelException if this working copy could not return in its original mode.
112          * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
113          * @since 3.0
114          */
115         void discardWorkingCopy() throws JavaModelException;
116 /**
117  * Creates and returns an import declaration in this compilation unit
118  * with the given name.
119  * <p>
120  * Optionally, the new element can be positioned before the specified
121  * sibling. If no sibling is specified, the element will be inserted
122  * as the last import declaration in this compilation unit.
123  * <p>
124  * If the compilation unit already includes the specified import declaration,
125  * the import is not generated (it does not generate duplicates).
126  * Note that it is valid to specify both a single-type import and an on-demand import
127  * for the same package, for example <code>"java.io.File"</code> and
128  * <code>"java.io.*"</code>, in which case both are preserved since the semantics
129  * of this are not the same as just importing <code>"java.io.*"</code>.
130  * Importing <code>"java.lang.*"</code>, or the package in which the compilation unit
131  * is defined, are not treated as special cases.  If they are specified, they are
132  * included in the result.
133  *
134  * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> or
135  *  <code>"java.awt.*"</code>)
136  * @param sibling the existing element which the import declaration will be inserted immediately before (if
137  *      <code> null </code>, then this import will be inserted as the last import declaration.
138  * @param monitor the progress monitor to notify
139  * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)
140  *
141  * @exception JavaModelException if the element could not be created. Reasons include:
142  * <ul>
143  * <li> This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
144  * <li> A <code>CoreException</code> occurred while updating an underlying resource
145  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
146  * <li> The name is not a valid import name (INVALID_NAME)
147  * </ul>
148  */
149 //IImportDeclaration createImport(String name, IJavaElement sibling, IProgressMonitor monitor) throws JavaModelException;
150 /**
151  * Creates and returns a package declaration in this compilation unit
152  * with the given package name.
153  *
154  * <p>If the compilation unit already includes the specified package declaration,
155  * it is not generated (it does not generate duplicates).
156  *
157  * @param name the name of the package declaration to add as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
158  * @param monitor the progress monitor to notify
159  * @return the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate)
160  *
161  * @exception JavaModelException if the element could not be created. Reasons include:
162  * <ul>
163  * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
164  * <li> A <code>CoreException</code> occurred while updating an underlying resource
165  * <li> The name is not a valid package name (INVALID_NAME)
166  * </ul>
167  */
168 // IPackageDeclaration createPackageDeclaration(String name, IProgressMonitor monitor) throws JavaModelException;   
169 /**
170  * Creates and returns a type in this compilation unit with the
171  * given contents. If this compilation unit does not exist, one
172  * will be created with an appropriate package declaration.
173  * <p>
174  * Optionally, the new type can be positioned before the specified
175  * sibling. If <code>sibling</code> is <code>null</code>, the type will be appended
176  * to the end of this compilation unit.
177  *
178  * <p>It is possible that a type with the same name already exists in this compilation unit.
179  * The value of the <code>force</code> parameter effects the resolution of
180  * such a conflict:<ul>
181  * <li> <code>true</code> - in this case the type is created with the new contents</li>
182  * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
183  * </ul>
184  *
185  * @param contents the source contents of the type declaration to add.
186  * @param sibling the existing element which the type will be inserted immediately before (if
187  *      <code> null </code>, then this type will be inserted as the last type declaration.
188  * @param force a <code> boolean </code> flag indicating how to deal with duplicates
189  * @param monitor the progress monitor to notify
190  * @return the newly inserted type
191  *
192  * @exception JavaModelException if the element could not be created. Reasons include:
193  * <ul>
194  * <li>The specified sibling element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
195  * <li> A <code>CoreException</code> occurred while updating an underlying resource
196  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
197  * <li> The contents could not be recognized as a type declaration (INVALID_CONTENTS)
198  * <li> There was a naming collision with an existing type (NAME_COLLISION)
199  * </ul>
200  */
201 //IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) throws JavaModelException;
202 /**
203  * Returns all types declared in this compilation unit in the order
204  * in which they appear in the source. 
205  * This includes all top-level types and nested member types.
206  * It does NOT include local types (types defined in methods).
207  *
208  * @return the array of top-level and member types defined in a compilation unit, in declaration order.
209  * @exception JavaModelException if this element does not exist or if an
210  *              exception occurs while accessing its corresponding resource
211  */
212 IType[] getAllTypes() throws JavaModelException;
213 /**
214  * Returns the smallest element within this compilation unit that 
215  * includes the given source position (that is, a method, field, etc.), or
216  * <code>null</code> if there is no element other than the compilation
217  * unit itself at the given position, or if the given position is not
218  * within the source range of this compilation unit.
219  *
220  * @param position a source position inside the compilation unit
221  * @return the innermost Java element enclosing a given source position or <code>null</code>
222  *      if none (excluding the compilation unit).
223  * @exception JavaModelException if the compilation unit does not exist or if an
224  *              exception occurs while accessing its corresponding resource
225  */
226 IJavaElement getElementAt(int position) throws JavaModelException;
227 /**
228  * Returns the first import declaration in this compilation unit with the given name.
229  * This is a handle-only method. The import declaration may or may not exist. This
230  * is a convenience method - imports can also be accessed from a compilation unit's
231  * import container.
232  *
233  * @param name the name of the import to find as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> 
234  *      or <code>"java.awt.*"</code>)
235  * @return a handle onto the corresponding import declaration. The import declaration may or may not exist.
236  */
237 //IImportDeclaration getImport(String name) ;
238 /**
239  * Returns the import container for this compilation unit.
240  * This is a handle-only method. The import container may or
241  * may not exist. The import container can used to access the 
242  * imports.
243  * @return a handle onto the corresponding import container. The 
244  *              import contain may or may not exist.
245  */
246 //IImportContainer getImportContainer();
247 /**
248  * Returns the import declarations in this compilation unit
249  * in the order in which they appear in the source. This is
250  * a convenience method - import declarations can also be
251  * accessed from a compilation unit's import container.
252  *
253  * @exception JavaModelException if this element does not exist or if an
254  *              exception occurs while accessing its corresponding resource
255  */
256 //IImportDeclaration[] getImports() throws JavaModelException;
257 /**
258  * Returns the first package declaration in this compilation unit with the given package name
259  * (there normally is at most one package declaration).
260  * This is a handle-only method. The package declaration may or may not exist.
261  *
262  * @param name the name of the package declaration as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
263  */
264 IPackageDeclaration getPackageDeclaration(String name);
265 /**
266  * Returns the package declarations in this compilation unit
267  * in the order in which they appear in the source.
268  * There normally is at most one package declaration.
269  *
270  * @return an array of package declaration (normally of size one)
271  *
272  * @exception JavaModelException if this element does not exist or if an
273  *              exception occurs while accessing its corresponding resource
274  */
275 //IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
276 /**
277  * Returns the primary compilation unit (whose owner is the primary owner)
278  * this working copy was created from, or this compilation unit if this a primary
279  * compilation unit.
280  * <p>
281  * Note that the returned primary compilation unit can be in working copy mode.
282  * </p>
283  * 
284  * @return the primary compilation unit this working copy was created from,
285  * or this compilation unit if it is primary
286  * @since 3.0
287  */
288 ICompilationUnit getPrimary();
289 /**
290  * Returns the top-level type declared in this compilation unit with the given simple type name.
291  * The type name has to be a valid compilation unit name.
292  * This is a handle-only method. The type may or may not exist.
293  *
294  * @param name the simple name of the requested type in the compilation unit
295  * @return a handle onto the corresponding type. The type may or may not exist.
296  * @see JavaConventions#validateCompilationUnitName(String name)
297  */
298 IType getType(String name);
299 /**
300  * Returns the top-level types declared in this compilation unit
301  * in the order in which they appear in the source.
302  *
303  * @exception JavaModelException if this element does not exist or if an
304  *              exception occurs while accessing its corresponding resource
305  */
306 IType[] getTypes() throws JavaModelException;
307
308 }