1 /*******************************************************************************
2 * Copyright (c) 2000, 2003 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.runtime.IProgressMonitor;
16 * Represents either a source type in a compilation unit (either a top-level
17 * type or a member type) or a binary type in a class file.
19 * If a binary type cannot be parsed, its structure remains unknown.
20 * Use <code>IJavaElement.isStructureKnown</code> to determine whether this
24 * The children are of type <code>IMember</code>, which includes <code>IField</code>,
25 * <code>IMethod</code>, <code>IInitializer</code> and <code>IType</code>.
26 * The children are listed in the order in which they appear in the source or class file.
29 * This interface is not intended to be implemented by clients.
32 public interface IType extends IMember, IParent {
34 * Do code completion inside a code snippet in the context of the current type.
36 * If the type can access to his source code and the insertion position is valid,
37 * then completion is performed against source. Otherwise the completion is performed
38 * against type structure and given locals variables.
40 * @param snippet the code snippet
41 * @param insertion the position with in source where the snippet
42 * is inserted. This position must not be in comments.
43 * A possible value is -1, if the position is not known.
44 * @param position the position with in snippet where the user
45 * is performing code assist.
46 * @param localVariableTypesNames an array (possibly empty) of fully qualified
47 * type names of local variables visible at the current scope
48 * @param localVariableNames an array (possibly empty) of local variable names
49 * that are visible at the current scope
50 * @param localVariableModifiers an array (possible empty) of modifiers for
52 * @param isStatic whether the current scope is in a static context
53 * @param requestor the completion requestor
60 // char[][] localVariableTypeNames,
61 // char[][] localVariableNames,
62 // int[] localVariableModifiers,
64 // ICompletionRequestor requestor)
65 // throws JavaModelException;
68 * Creates and returns a field in this type with the
71 * Optionally, the new element can be positioned before the specified
72 * sibling. If no sibling is specified, the element will be inserted
73 * as the last field declaration in this type.</p>
75 * <p>It is possible that a field with the same name already exists in this type.
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 field is created with the new contents</li>
79 * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
82 * @param contents the given contents
83 * @param sibling the given sibling
84 * @param force a flag in case the same name already exists in this type
85 * @param monitor the given progress monitor
86 * @exception JavaModelException if the element could not be created. Reasons include:
88 * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
89 * <li> A <code>CoreException</code> occurred while updating an underlying resource
90 * <li> The specified sibling is not a child of this type (INVALID_SIBLING)
91 * <li> The contents could not be recognized as a field declaration (INVALID_CONTENTS)
92 * <li> This type is read-only (binary) (READ_ONLY)
93 * <li> There was a naming collision with an existing field (NAME_COLLISION)
95 * @return a field in this type with the given contents
97 // IField createField(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
98 // throws JavaModelException;
101 * Creates and returns a static initializer in this type with the
104 * Optionally, the new element can be positioned before the specified
105 * sibling. If no sibling is specified, the new initializer is positioned
106 * after the last existing initializer declaration, or as the first member
107 * in the type if there are no initializers.</p>
109 * @param contents the given contents
110 * @param sibling the given sibling
111 * @param monitor the given progress monitor
112 * @exception JavaModelException if the element could not be created. Reasons include:
114 * <li> This element does not exist
115 * <li> A <code>CoreException</code> occurred while updating an underlying resource
116 * <li> The specified sibling is not a child of this type (INVALID_SIBLING)
117 * <li> The contents could not be recognized as an initializer declaration (INVALID_CONTENTS)
118 * <li> This type is read-only (binary) (READ_ONLY)
120 * @return a static initializer in this type with the given contents
122 // IInitializer createInitializer(String contents, IJavaElement sibling, IProgressMonitor monitor)
123 // throws JavaModelException;
126 * Creates and returns a method or constructor in this type with the
129 * Optionally, the new element can be positioned before the specified
130 * sibling. If no sibling is specified, the element will be appended
133 * <p>It is possible that a method with the same signature already exists in this type.
134 * The value of the <code>force</code> parameter effects the resolution of
135 * such a conflict:<ul>
136 * <li> <code>true</code> - in this case the method is created with the new contents</li>
137 * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
140 * @param contents the given contents
141 * @param sibling the given sibling
142 * @param force a flag in case the same name already exists in this type
143 * @param monitor the given progress monitor
144 * @exception JavaModelException if the element could not be created. Reasons include:
146 * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
147 * <li> A <code>CoreException</code> occurred while updating an underlying resource
148 * <li> The specified sibling is not a child of this type (INVALID_SIBLING)
149 * <li> The contents could not be recognized as a method or constructor
150 * declaration (INVALID_CONTENTS)
151 * <li> This type is read-only (binary) (READ_ONLY)
152 * <li> There was a naming collision with an existing method (NAME_COLLISION)
154 * @return a method or constructor in this type with the given contents
156 // IMethod createMethod(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
157 // throws JavaModelException;
160 * Creates and returns a type in this type with the
163 * Optionally, the new type can be positioned before the specified
164 * sibling. If no sibling is specified, the type will be appended
167 * <p>It is possible that a type with the same name already exists in this type.
168 * The value of the <code>force</code> parameter effects the resolution of
169 * such a conflict:<ul>
170 * <li> <code>true</code> - in this case the type is created with the new contents</li>
171 * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
174 * @param contents the given contents
175 * @param sibling the given sibling
176 * @param force a flag in case the same name already exists in this type
177 * @param monitor the given progress monitor
178 * @exception JavaModelException if the element could not be created. Reasons include:
180 * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
181 * <li> A <code>CoreException</code> occurred while updating an underlying resource
182 * <li> The specified sibling is not a child of this type (INVALID_SIBLING)
183 * <li> The contents could not be recognized as a type declaration (INVALID_CONTENTS)
184 * <li> This type is read-only (binary) (READ_ONLY)
185 * <li> There was a naming collision with an existing field (NAME_COLLISION)
187 * @return a type in this type with the given contents
189 // IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
190 // throws JavaModelException;
193 * Finds the methods in this type that correspond to
195 * A method m1 corresponds to another method m2 if:
197 * <li>m1 has the same element name as m2.
198 * <li>m1 has the same number of arguments as m2 and
199 * the simple names of the argument types must be equals.
202 * @param method the given method
203 * @return the found method or <code>null</code> if no such methods can be found.
207 IMethod[] findMethods(IMethod method);
210 * Returns the simple name of this type, unqualified by package or enclosing type.
211 * This is a handle-only method.
213 * @return the simple name of this type
215 String getElementName();
218 * Returns the field with the specified name
219 * in this type (for example, <code>"bar"</code>).
220 * This is a handle-only method. The field may or may not exist.
222 * @param name the given name
223 * @return the field with the specified name in this type
225 IField getField(String name);
228 * Returns the fields declared by this type.
229 * If this is a source type, the results are listed in the order
230 * in which they appear in the source, otherwise, the results are
231 * in no particular order. For binary types, this includes synthetic fields.
233 * @exception JavaModelException if this element does not exist or if an
234 * exception occurs while accessing its corresponding resource.
235 * @return the fields declared by this type
237 IField[] getFields() throws JavaModelException;
240 * Returns the fully qualified name of this type,
241 * including qualification for any containing types and packages.
242 * This is the name of the package, followed by <code>'.'</code>,
243 * followed by the type-qualified name.
244 * This is a handle-only method.
246 * @see IType#getTypeQualifiedName()
247 * @return the fully qualified name of this type
249 String getFullyQualifiedName();
252 * Returns the fully qualified name of this type,
253 * including qualification for any containing types and packages.
254 * This is the name of the package, followed by <code>'.'</code>,
255 * followed by the type-qualified name using the <code>enclosingTypeSeparator</code>.
259 * <li>the fully qualified name of a class B defined as a member of a class A in a compilation unit A.java
260 * in a package x.y using the '.' separator is "x.y.A.B"</li>
261 * <li>the fully qualified name of a class B defined as a member of a class A in a compilation unit A.java
262 * in a package x.y using the '$' separator is "x.y.A$B"</li>
263 * <li>the fully qualified name of a binary type whose class file is x/y/A$B.class
264 * using the '.' separator is "x.y.A.B"</li>
265 * <li>the fully qualified name of a binary type whose class file is x/y/A$B.class
266 * using the '$' separator is "x.y.A$B"</li>
267 * <li>the fully qualified name of an anonymous binary type whose class file is x/y/A$1.class
268 * using the '.' separator is "x.y.A$1"</li>
271 * This is a handle-only method.
273 * @param enclosingTypeSeparator the given enclosing type separator
274 * @return the fully qualified name of this type, including qualification for any containing types and packages
275 * @see IType#getTypeQualifiedName(char)
278 String getFullyQualifiedName(char enclosingTypeSeparator);
281 * Returns the initializer with the specified position relative to
282 * the order they are defined in the source.
283 * Numbering starts at 1 (thus the first occurrence is occurrence 1, not occurrence 0).
284 * This is a handle-only method. The initializer may or may not be present.
286 * @param occurrenceCount the specified position
287 * @return the initializer with the specified position relative to the order they are defined in the source
289 // IInitializer getInitializer(int occurrenceCount);
292 * Returns the initializers declared by this type.
293 * For binary types this is an empty collection.
294 * If this is a source type, the results are listed in the order
295 * in which they appear in the source.
297 * @exception JavaModelException if this element does not exist or if an
298 * exception occurs while accessing its corresponding resource.
299 * @return the initializers declared by this type
301 // IInitializer[] getInitializers() throws JavaModelException;
304 * Returns the method with the specified name and parameter types
305 * in this type (for example, <code>"foo", {"I", "QString;"}</code>). To get the
306 * handle for a constructor, the name specified must be the simple
307 * name of the enclosing type.
308 * This is a handle-only method. The method may or may not be present.
310 * @param name the given name
311 * @param parameterTypeSignatures the given parameter types
312 * @return the method with the specified name and parameter types in this type
314 IMethod getMethod(String name, String[] parameterTypeSignatures);
317 * Returns the methods and constructors declared by this type.
318 * For binary types, this may include the special <code><clinit></code>; method
319 * and synthetic methods.
320 * If this is a source type, the results are listed in the order
321 * in which they appear in the source, otherwise, the results are
322 * in no particular order.
324 * @exception JavaModelException if this element does not exist or if an
325 * exception occurs while accessing its corresponding resource.
326 * @return the methods and constructors declared by this type
328 IMethod[] getMethods() throws JavaModelException;
331 * Returns the package fragment in which this element is defined.
332 * This is a handle-only method.
334 * @return the package fragment in which this element is defined
336 IPackageFragment getPackageFragment();
339 * Returns the name of this type's superclass, or <code>null</code>
340 * for source types that do not specify a superclass.
341 * For interfaces, the superclass name is always <code>"java.lang.Object"</code>.
342 * For source types, the name as declared is returned, for binary types,
343 * the resolved, qualified name is returned.
345 * @exception JavaModelException if this element does not exist or if an
346 * exception occurs while accessing its corresponding resource.
347 * @return the name of this type's superclass, or <code>null</code> for source types that do not specify a superclass
349 String getSuperclassName() throws JavaModelException;
352 * Returns the names of interfaces that this type implements or extends,
353 * in the order in which they are listed in the source.
354 * For classes, this gives the interfaces that this class implements.
355 * For interfaces, this gives the interfaces that this interface extends.
356 * An empty collection is returned if this type does not implement or
357 * extend any interfaces. For source types, simple names are returned,
358 * for binary types, qualified names are returned.
360 * @exception JavaModelException if this element does not exist or if an
361 * exception occurs while accessing its corresponding resource.
362 * @return the names of interfaces that this type implements or extends, in the order in which they are listed in the source,
363 * an empty collection if none
365 String[] getSuperInterfaceNames() throws JavaModelException;
368 * Returns the member type declared in this type with the given simple name.
369 * This is a handle-only method. The type may or may not exist.
371 * @param the given simple name
372 * @return the member type declared in this type with the given simple name
374 IType getType(String name);
377 * Returns the type-qualified name of this type,
378 * including qualification for any enclosing types,
379 * but not including package qualification.
380 * For source types, this consists of the simple names of
381 * any enclosing types, separated by <code>"$"</code>, followed by the simple name of this type.
382 * For binary types, this is the name of the class file without the ".class" suffix.
383 * This is a handle-only method.
385 * @return the type-qualified name of this type
387 String getTypeQualifiedName();
390 * Returns the type-qualified name of this type,
391 * including qualification for any enclosing types,
392 * but not including package qualification.
393 * This consists of the simple names of any enclosing types,
394 * separated by the <code>enclosingTypeSeparator</code>,
395 * followed by the simple name of this type.
399 * <li>the type qualified name of a class B defined as a member of a class A
400 * using the '.' separator is "A.B"</li>
401 * <li>the type qualified name of a class B defined as a member of a class A
402 * using the '$' separator is "A$B"</li>
403 * <li>the type qualified name of a binary type whose class file is A$B.class
404 * using the '.' separator is "A.B"</li>
405 * <li>the type qualified name of a binary type whose class file is A$B.class
406 * using the '$' separator is "A$B"</li>
407 * <li>the type qualified name of an anonymous binary type whose class file is A$1.class
408 * using the '.' separator is "A$1"</li>
411 * This is a handle-only method.
413 * @param enclosingTypeSeparator the specified enclosing type separator
414 * @return the type-qualified name of this type
417 String getTypeQualifiedName(char enclosingTypeSeparator);
420 * Returns the immediate member types declared by this type.
421 * The results are listed in the order in which they appear in the source or class file.
423 * @exception JavaModelException if this element does not exist or if an
424 * exception occurs while accessing its corresponding resource.
425 * @return the immediate member types declared by this type
427 IType[] getTypes() throws JavaModelException;
430 * Returns whether this type represents an anonymous type.
432 * @exception JavaModelException if this element does not exist or if an
433 * exception occurs while accessing its corresponding resource.
434 * @return true if this type represents an anonymous type, false otherwise
437 boolean isAnonymous() throws JavaModelException;
440 * Returns whether this type represents a class.
442 * @exception JavaModelException if this element does not exist or if an
443 * exception occurs while accessing its corresponding resource.
444 * @return true if this type represents a class, false otherwise
446 boolean isClass() throws JavaModelException;
449 * Returns whether this type represents an interface.
451 * @exception JavaModelException if this element does not exist or if an
452 * exception occurs while accessing its corresponding resource.
453 * @return true if this type represents an interface, false otherwise
455 boolean isInterface() throws JavaModelException;
458 * Returns whether this type represents a local type.
460 * @exception JavaModelException if this element does not exist or if an
461 * exception occurs while accessing its corresponding resource.
462 * @return true if this type represents a local type, false otherwise
465 boolean isLocal() throws JavaModelException;
468 * Returns whether this type represents a member type.
470 * @exception JavaModelException if this element does not exist or if an
471 * exception occurs while accessing its corresponding resource.
472 * @return true if this type represents a member type, false otherwise
475 boolean isMember() throws JavaModelException;
477 * Loads a previously saved ITypeHierarchy from an input stream. A type hierarchy can
478 * be stored using ITypeHierachy#store(OutputStream).
480 * Only hierarchies originally created by the following methods can be load:
482 * <li>IType#newSupertypeHierarchy(IProgressMonitor)</li>
483 * <li>IType#newTypeHierarchy(IJavaProject, IProgressMonitor)</li>
484 * <li>IType#newTypeHierarchy(IProgressMonitor)</li>
487 * @param input stream where hierarchy will be read
488 * @param monitor the given progress monitor
489 * @return the stored hierarchy
490 * @exception JavaModelException if the hierarchy could not be restored, reasons include:
491 * - type is not the focus of the hierarchy or
492 * - unable to read the input stream (wrong format, IOException during reading, ...)
493 * @see ITypeHierarchy#store(OutputStream, IProgressMonitor)
496 // ITypeHierarchy loadTypeHierachy(InputStream input, IProgressMonitor monitor) throws JavaModelException;
498 * Creates and returns a type hierarchy for this type containing
499 * this type and all of its supertypes.
501 * @exception JavaModelException if this element does not exist or if an
502 * exception occurs while accessing its corresponding resource.
503 * @param monitor the given progress monitor
504 * @return a type hierarchy for this type containing this type and all of its supertypes
506 // ITypeHierarchy newSupertypeHierarchy(IProgressMonitor monitor) throws JavaModelException;
509 * Creates and returns a type hierarchy for this type containing
510 * this type and all of its supertypes, considering types in the given
511 * working copies. In other words, the list of working copies will take
512 * precedence over their original compilation units in the workspace.
514 * Note that passing an empty working copy will be as if the original compilation
515 * unit had been deleted.
517 * @param workingCopies the working copies that take precedence over their original compilation units
518 * @param monitor the given progress monitor
519 * @return a type hierarchy for this type containing this type and all of its supertypes
520 * @exception JavaModelException if this element does not exist or if an
521 * exception occurs while accessing its corresponding resource.
524 // ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[] workingCopies, IProgressMonitor monitor)
525 // throws JavaModelException;
528 * Creates and returns a type hierarchy for this type containing
529 * this type, all of its supertypes, and all its subtypes in the workspace.
531 * @exception JavaModelException if this element does not exist or if an
532 * exception occurs while accessing its corresponding resource.
533 * @param monitor the given progress monitor
534 * @return a type hierarchy for this type containing
535 * this type, all of its supertypes, and all its subtypes in the workspace
537 // ITypeHierarchy newTypeHierarchy(IProgressMonitor monitor) throws JavaModelException;
540 * Creates and returns a type hierarchy for this type containing
541 * this type, all of its supertypes, and all its subtypes in the workspace,
542 * considering types in the given working copies. In other words, the list of working
543 * copies that will take precedence over their original compilation units in the workspace.
545 * Note that passing an empty working copy will be as if the original compilation
546 * unit had been deleted.
548 * @param workingCopies the working copies that take precedence over their original compilation units
549 * @param monitor the given progress monitor
550 * @return a type hierarchy for this type containing
551 * this type, all of its supertypes, and all its subtypes in the workspace
552 * @exception JavaModelException if this element does not exist or if an
553 * exception occurs while accessing its corresponding resource.
556 // ITypeHierarchy newTypeHierarchy(IWorkingCopy[] workingCopies, IProgressMonitor monitor) throws JavaModelException;
559 * Creates and returns a type hierarchy for this type containing
560 * this type, all of its supertypes, and all its subtypes
561 * in the context of the given project.
563 * @param project the given project
564 * @param monitor the given progress monitor
565 * @exception JavaModelException if this element does not exist or if an
566 * exception occurs while accessing its corresponding resource.
567 * @return a type hierarchy for this type containing
568 * this type, all of its supertypes, and all its subtypes
569 * in the context of the given project
571 // ITypeHierarchy newTypeHierarchy(IJavaProject project, IProgressMonitor monitor) throws JavaModelException;
574 * Resolves the given type name within the context of this type (depending on the type hierarchy
575 * and its imports). Multiple answers might be found in case there are ambiguous matches.
577 * Each matching type name is decomposed as an array of two strings, the first denoting the package
578 * name (dot-separated) and the second being the type name.
579 * Returns <code>null</code> if unable to find any matching type.
581 * For example, resolution of <code>"Object"</code> would typically return
582 * <code>{{"java.lang", "Object"}}</code>.
584 * @param typeName the given type name
585 * @exception JavaModelException if code resolve could not be performed.
586 * @return the resolved type names or <code>null</code> if unable to find any matching type
588 // String[][] resolveType(String typeName) throws JavaModelException;