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;
14 * Represents either a source type in a compilation unit (either a top-level
15 * type or a member type) or a binary type in a class file.
17 * If a binary type cannot be parsed, its structure remains unknown. Use
18 * <code>IJavaElement.isStructureKnown</code> to determine whether this is the
22 * The children are of type <code>IMember</code>, which includes
23 * <code>IField</code>, <code>IMethod</code>, <code>IInitializer</code>
24 * and <code>IType</code>. The children are listed in the order in which they
25 * appear in the source or class file.
28 * This interface is not intended to be implemented by clients.
31 public interface IType extends IMember, IParent {
33 * Do code completion inside a code snippet in the context of the current
36 * If the type can access to his source code and the insertion position is
37 * valid, then completion is performed against source. Otherwise the
38 * completion is performed against type structure and given locals
44 * the position with in source where the snippet is inserted.
45 * This position must not be in comments. A possible value is -1,
46 * if the position is not known.
48 * the position with in snippet where the user is performing code
50 * @param localVariableTypesNames
51 * an array (possibly empty) of fully qualified type names of
52 * local variables visible at the current scope
53 * @param localVariableNames
54 * an array (possibly empty) of local variable names that are
55 * visible at the current scope
56 * @param localVariableModifiers
57 * an array (possible empty) of modifiers for local variables
59 * whether the current scope is in a static context
61 * the completion requestor
68 // char[][] localVariableTypeNames,
69 // char[][] localVariableNames,
70 // int[] localVariableModifiers,
72 // ICompletionRequestor requestor)
73 // throws JavaModelException;
75 * Creates and returns a field in this type with the given contents.
77 * Optionally, the new element can be positioned before the specified
78 * sibling. If no sibling is specified, the element will be inserted as the
79 * last field declaration in this type.
83 * It is possible that a field with the same name already exists in this
84 * type. The value of the <code>force</code> parameter effects the
85 * resolution of such a conflict:
87 * <li> <code>true</code> - in this case the field is created with the new
89 * <li> <code>false</code> - in this case a
90 * <code>JavaModelException</code> is thrown</li>
99 * a flag in case the same name already exists in this type
101 * the given progress monitor
102 * @exception JavaModelException
103 * if the element could not be created. Reasons include:
105 * <li> This Java element does not exist
106 * (ELEMENT_DOES_NOT_EXIST)</li>
107 * <li> A <code>CoreException</code> occurred while
108 * updating an underlying resource
109 * <li> The specified sibling is not a child of this type
111 * <li> The contents could not be recognized as a field
112 * declaration (INVALID_CONTENTS)
113 * <li> This type is read-only (binary) (READ_ONLY)
114 * <li> There was a naming collision with an existing field
117 * @return a field in this type with the given contents
119 // IField createField(String contents, IJavaElement sibling, boolean force,
120 // IProgressMonitor monitor)
121 // throws JavaModelException;
123 * Creates and returns a static initializer in this type with the given
126 * Optionally, the new element can be positioned before the specified
127 * sibling. If no sibling is specified, the new initializer is positioned
128 * after the last existing initializer declaration, or as the first member
129 * in the type if there are no initializers.
137 * the given progress monitor
138 * @exception JavaModelException
139 * if the element could not be created. Reasons include:
141 * <li> This element does not exist
142 * <li> A <code>CoreException</code> occurred while
143 * updating an underlying resource
144 * <li> The specified sibling is not a child of this type
146 * <li> The contents could not be recognized as an
147 * initializer declaration (INVALID_CONTENTS)
148 * <li> This type is read-only (binary) (READ_ONLY)
150 * @return a static initializer in this type with the given contents
152 // IInitializer createInitializer(String contents, IJavaElement sibling,
153 // IProgressMonitor monitor)
154 // throws JavaModelException;
156 * Creates and returns a method or constructor in this type with the given
159 * Optionally, the new element can be positioned before the specified
160 * sibling. If no sibling is specified, the element will be appended to this
164 * It is possible that a method with the same signature already exists in
165 * this type. The value of the <code>force</code> parameter effects the
166 * resolution of such a conflict:
168 * <li> <code>true</code> - in this case the method is created with the
170 * <li> <code>false</code> - in this case a
171 * <code>JavaModelException</code> is thrown</li>
180 * a flag in case the same name already exists in this type
182 * the given progress monitor
183 * @exception JavaModelException
184 * if the element could not be created. Reasons include:
186 * <li> This Java element does not exist
187 * (ELEMENT_DOES_NOT_EXIST)</li>
188 * <li> A <code>CoreException</code> occurred while
189 * updating an underlying resource
190 * <li> The specified sibling is not a child of this type
192 * <li> The contents could not be recognized as a method or
193 * constructor declaration (INVALID_CONTENTS)
194 * <li> This type is read-only (binary) (READ_ONLY)
195 * <li> There was a naming collision with an existing method
198 * @return a method or constructor in this type with the given contents
200 // IMethod createMethod(String contents, IJavaElement sibling, boolean
201 // force, IProgressMonitor monitor)
202 // throws JavaModelException;
204 * Creates and returns a type in this type with the given contents.
206 * Optionally, the new type can be positioned before the specified sibling.
207 * If no sibling is specified, the type will be appended to this type.
210 * It is possible that a type with the same name already exists in this
211 * type. The value of the <code>force</code> parameter effects the
212 * resolution of such a conflict:
214 * <li> <code>true</code> - in this case the type is created with the new
216 * <li> <code>false</code> - in this case a
217 * <code>JavaModelException</code> is thrown</li>
226 * a flag in case the same name already exists in this type
228 * the given progress monitor
229 * @exception JavaModelException
230 * if the element could not be created. Reasons include:
232 * <li> This Java element does not exist
233 * (ELEMENT_DOES_NOT_EXIST)</li>
234 * <li> A <code>CoreException</code> occurred while
235 * updating an underlying resource
236 * <li> The specified sibling is not a child of this type
238 * <li> The contents could not be recognized as a type
239 * declaration (INVALID_CONTENTS)
240 * <li> This type is read-only (binary) (READ_ONLY)
241 * <li> There was a naming collision with an existing field
244 * @return a type in this type with the given contents
246 // IType createType(String contents, IJavaElement sibling, boolean force,
247 // IProgressMonitor monitor)
248 // throws JavaModelException;
250 * Finds the methods in this type that correspond to the given method. A
251 * method m1 corresponds to another method m2 if:
253 * <li>m1 has the same element name as m2.
254 * <li>m1 has the same number of arguments as m2 and the simple names of
255 * the argument types must be equals.
261 * @return the found method or <code>null</code> if no such methods can be
266 IMethod[] findMethods(IMethod method);
269 * Returns the simple name of this type, unqualified by package or enclosing
270 * type. This is a handle-only method.
272 * @return the simple name of this type
274 String getElementName();
277 * Returns the field with the specified name in this type (for example,
278 * <code>"bar"</code>). This is a handle-only method. The field may or
283 * @return the field with the specified name in this type
285 IField getField(String name);
288 * Returns the fields declared by this type. If this is a source type, the
289 * results are listed in the order in which they appear in the source,
290 * otherwise, the results are in no particular order. For binary types, this
291 * includes synthetic fields.
293 * @exception JavaModelException
294 * if this element does not exist or if an exception occurs
295 * while accessing its corresponding resource.
296 * @return the fields declared by this type
298 IField[] getFields() throws JavaModelException;
301 * Returns the fully qualified name of this type, including qualification
302 * for any containing types and packages. This is the name of the package,
303 * followed by <code>'.'</code>, followed by the type-qualified name.
304 * This is a handle-only method.
306 * @see IType#getTypeQualifiedName()
307 * @return the fully qualified name of this type
309 String getFullyQualifiedName();
312 * Returns the fully qualified name of this type, including qualification
313 * for any containing types and packages. This is the name of the package,
314 * followed by <code>'.'</code>, followed by the type-qualified name
315 * using the <code>enclosingTypeSeparator</code>.
319 * <li>the fully qualified name of a class B defined as a member of a class
320 * A in a compilation unit A.java in a package x.y using the '.' separator
322 * <li>the fully qualified name of a class B defined as a member of a class
323 * A in a compilation unit A.java in a package x.y using the '$' separator
325 * <li>the fully qualified name of a binary type whose class file is
326 * x/y/A$B.class using the '.' separator is "x.y.A.B"</li>
327 * <li>the fully qualified name of a binary type whose class file is
328 * x/y/A$B.class using the '$' separator is "x.y.A$B"</li>
329 * <li>the fully qualified name of an anonymous binary type whose class
330 * file is x/y/A$1.class using the '.' separator is "x.y.A$1"</li>
333 * This is a handle-only method.
335 * @param enclosingTypeSeparator
336 * the given enclosing type separator
337 * @return the fully qualified name of this type, including qualification
338 * for any containing types and packages
339 * @see IType#getTypeQualifiedName(char)
342 String getFullyQualifiedName(char enclosingTypeSeparator);
345 * Returns the initializer with the specified position relative to the order
346 * they are defined in the source. Numbering starts at 1 (thus the first
347 * occurrence is occurrence 1, not occurrence 0). This is a handle-only
348 * method. The initializer may or may not be present.
350 * @param occurrenceCount
351 * the specified position
352 * @return the initializer with the specified position relative to the order
353 * they are defined in the source
355 // IInitializer getInitializer(int occurrenceCount);
357 * Returns the initializers declared by this type. For binary types this is
358 * an empty collection. If this is a source type, the results are listed in
359 * the order in which they appear in the source.
361 * @exception JavaModelException
362 * if this element does not exist or if an exception occurs
363 * while accessing its corresponding resource.
364 * @return the initializers declared by this type
366 // IInitializer[] getInitializers() throws JavaModelException;
368 * Returns the method with the specified name and parameter types in this
369 * type (for example, <code>"foo", {"I", "QString;"}</code>). To get the
370 * handle for a constructor, the name specified must be the simple name of
371 * the enclosing type. This is a handle-only method. The method may or may
376 * @param parameterTypeSignatures
377 * the given parameter types
378 * @return the method with the specified name and parameter types in this
381 IMethod getMethod(String name, String[] parameterTypeSignatures);
384 * Returns the methods and constructors declared by this type. For binary
385 * types, this may include the special <code><clinit></code>; method
386 * and synthetic methods. If this is a source type, the results are listed
387 * in the order in which they appear in the source, otherwise, the results
388 * are in no particular order.
390 * @exception JavaModelException
391 * if this element does not exist or if an exception occurs
392 * while accessing its corresponding resource.
393 * @return the methods and constructors declared by this type
395 IMethod[] getMethods() throws JavaModelException;
398 * Returns the package fragment in which this element is defined. This is a
399 * handle-only method.
401 * @return the package fragment in which this element is defined
403 IPackageFragment getPackageFragment();
406 * Returns the name of this type's superclass, or <code>null</code> for
407 * source types that do not specify a superclass. For interfaces, the
408 * superclass name is always <code>"java.lang.Object"</code>. For source
409 * types, the name as declared is returned, for binary types, the resolved,
410 * qualified name is returned.
412 * @exception JavaModelException
413 * if this element does not exist or if an exception occurs
414 * while accessing its corresponding resource.
415 * @return the name of this type's superclass, or <code>null</code> for
416 * source types that do not specify a superclass
418 String getSuperclassName() throws JavaModelException;
421 * Returns the names of interfaces that this type implements or extends, in
422 * the order in which they are listed in the source. For classes, this gives
423 * the interfaces that this class implements. For interfaces, this gives the
424 * interfaces that this interface extends. An empty collection is returned
425 * if this type does not implement or extend any interfaces. For source
426 * types, simple names are returned, for binary types, qualified names are
429 * @exception JavaModelException
430 * if this element does not exist or if an exception occurs
431 * while accessing its corresponding resource.
432 * @return the names of interfaces that this type implements or extends, in
433 * the order in which they are listed in the source, an empty
436 String[] getSuperInterfaceNames() throws JavaModelException;
439 * Returns the member type declared in this type with the given simple name.
440 * This is a handle-only method. The type may or may not exist.
444 * @return the member type declared in this type with the given simple name
446 IType getType(String name);
449 * Returns the type-qualified name of this type, including qualification for
450 * any enclosing types, but not including package qualification. For source
451 * types, this consists of the simple names of any enclosing types,
452 * separated by <code>"$"</code>, followed by the simple name of this
453 * type. For binary types, this is the name of the class file without the
454 * ".class" suffix. This is a handle-only method.
456 * @return the type-qualified name of this type
458 String getTypeQualifiedName();
461 * Returns the type-qualified name of this type, including qualification for
462 * any enclosing types, but not including package qualification. This
463 * consists of the simple names of any enclosing types, separated by the
464 * <code>enclosingTypeSeparator</code>, followed by the simple name of
469 * <li>the type qualified name of a class B defined as a member of a class
470 * A using the '.' separator is "A.B"</li>
471 * <li>the type qualified name of a class B defined as a member of a class
472 * A using the '$' separator is "A$B"</li>
473 * <li>the type qualified name of a binary type whose class file is
474 * A$B.class using the '.' separator is "A.B"</li>
475 * <li>the type qualified name of a binary type whose class file is
476 * A$B.class using the '$' separator is "A$B"</li>
477 * <li>the type qualified name of an anonymous binary type whose class file
478 * is A$1.class using the '.' separator is "A$1"</li>
481 * This is a handle-only method.
483 * @param enclosingTypeSeparator
484 * the specified enclosing type separator
485 * @return the type-qualified name of this type
488 String getTypeQualifiedName(char enclosingTypeSeparator);
491 * Returns the immediate member types declared by this type. The results are
492 * listed in the order in which they appear in the source or class file.
494 * @exception JavaModelException
495 * if this element does not exist or if an exception occurs
496 * while accessing its corresponding resource.
497 * @return the immediate member types declared by this type
499 IType[] getTypes() throws JavaModelException;
502 * Returns whether this type represents an anonymous type.
504 * @exception JavaModelException
505 * if this element does not exist or if an exception occurs
506 * while accessing its corresponding resource.
507 * @return true if this type represents an anonymous type, false otherwise
510 boolean isAnonymous() throws JavaModelException;
513 * Returns whether this type represents a class.
515 * @exception JavaModelException
516 * if this element does not exist or if an exception occurs
517 * while accessing its corresponding resource.
518 * @return true if this type represents a class, false otherwise
520 boolean isClass() throws JavaModelException;
523 * Returns whether this type represents an interface.
525 * @exception JavaModelException
526 * if this element does not exist or if an exception occurs
527 * while accessing its corresponding resource.
528 * @return true if this type represents an interface, false otherwise
530 boolean isInterface() throws JavaModelException;
533 * Returns whether this type represents a local type.
535 * @exception JavaModelException
536 * if this element does not exist or if an exception occurs
537 * while accessing its corresponding resource.
538 * @return true if this type represents a local type, false otherwise
541 boolean isLocal() throws JavaModelException;
544 * Returns whether this type represents a member type.
546 * @exception JavaModelException
547 * if this element does not exist or if an exception occurs
548 * while accessing its corresponding resource.
549 * @return true if this type represents a member type, false otherwise
552 boolean isMember() throws JavaModelException;
554 * Loads a previously saved ITypeHierarchy from an input stream. A type
555 * hierarchy can be stored using ITypeHierachy#store(OutputStream).
557 * Only hierarchies originally created by the following methods can be load:
559 * <li>IType#newSupertypeHierarchy(IProgressMonitor)</li>
560 * <li>IType#newTypeHierarchy(IJavaProject, IProgressMonitor)</li>
561 * <li>IType#newTypeHierarchy(IProgressMonitor)</li>
565 * stream where hierarchy will be read
567 * the given progress monitor
568 * @return the stored hierarchy
569 * @exception JavaModelException
570 * if the hierarchy could not be restored, reasons include: -
571 * type is not the focus of the hierarchy or - unable to read
572 * the input stream (wrong format, IOException during
574 * @see ITypeHierarchy#store(OutputStream, IProgressMonitor)
577 // ITypeHierarchy loadTypeHierachy(InputStream input, IProgressMonitor
578 // monitor) throws JavaModelException;
580 * Creates and returns a type hierarchy for this type containing this type
581 * and all of its supertypes.
583 * @exception JavaModelException
584 * if this element does not exist or if an exception occurs
585 * while accessing its corresponding resource.
587 * the given progress monitor
588 * @return a type hierarchy for this type containing this type and all of
591 // ITypeHierarchy newSupertypeHierarchy(IProgressMonitor monitor) throws
592 // JavaModelException;
594 * Creates and returns a type hierarchy for this type containing this type
595 * and all of its supertypes, considering types in the given working copies.
596 * In other words, the list of working copies will take precedence over
597 * their original compilation units in the workspace.
599 * Note that passing an empty working copy will be as if the original
600 * compilation unit had been deleted.
602 * @param workingCopies
603 * the working copies that take precedence over their original
606 * the given progress monitor
607 * @return a type hierarchy for this type containing this type and all of
609 * @exception JavaModelException
610 * if this element does not exist or if an exception occurs
611 * while accessing its corresponding resource.
614 // ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[] workingCopies,
615 // IProgressMonitor monitor)
616 // throws JavaModelException;
618 * Creates and returns a type hierarchy for this type containing this type,
619 * all of its supertypes, and all its subtypes in the workspace.
621 * @exception JavaModelException
622 * if this element does not exist or if an exception occurs
623 * while accessing its corresponding resource.
625 * the given progress monitor
626 * @return a type hierarchy for this type containing this type, all of its
627 * supertypes, and all its subtypes in the workspace
629 // ITypeHierarchy newTypeHierarchy(IProgressMonitor monitor) throws
630 // JavaModelException;
632 * Creates and returns a type hierarchy for this type containing this type,
633 * all of its supertypes, and all its subtypes in the workspace, considering
634 * types in the given working copies. In other words, the list of working
635 * copies that will take precedence over their original compilation units in
638 * Note that passing an empty working copy will be as if the original
639 * compilation unit had been deleted.
641 * @param workingCopies
642 * the working copies that take precedence over their original
645 * the given progress monitor
646 * @return a type hierarchy for this type containing this type, all of its
647 * supertypes, and all its subtypes in the workspace
648 * @exception JavaModelException
649 * if this element does not exist or if an exception occurs
650 * while accessing its corresponding resource.
653 // ITypeHierarchy newTypeHierarchy(IWorkingCopy[] workingCopies,
654 // IProgressMonitor monitor) throws JavaModelException;
656 * Creates and returns a type hierarchy for this type containing this type,
657 * all of its supertypes, and all its subtypes in the workspace, considering
658 * types in the working copies with the given owner. In other words, the
659 * owner's working copies will take precedence over their original
660 * compilation units in the workspace.
662 * Note that if a working copy is empty, it will be as if the original
663 * compilation unit had been deleted.
667 * the owner of working copies that take precedence over their
668 * original compilation units
670 * the given progress monitor
671 * @return a type hierarchy for this type containing this type, all of its
672 * supertypes, and all its subtypes in the workspace
673 * @exception JavaModelException
674 * if this element does not exist or if an exception occurs
675 * while accessing its corresponding resource.
678 // ITypeHierarchy newTypeHierarchy(WorkingCopyOwner owner, IProgressMonitor
679 // monitor) throws JavaModelException;
681 * Creates and returns a type hierarchy for this type containing this type,
682 * all of its supertypes, and all its subtypes in the context of the given
688 * the given progress monitor
689 * @exception JavaModelException
690 * if this element does not exist or if an exception occurs
691 * while accessing its corresponding resource.
692 * @return a type hierarchy for this type containing this type, all of its
693 * supertypes, and all its subtypes in the context of the given
696 // ITypeHierarchy newTypeHierarchy(IJavaProject project, IProgressMonitor
697 // monitor) throws JavaModelException;
699 * Resolves the given type name within the context of this type (depending
700 * on the type hierarchy and its imports). Multiple answers might be found
701 * in case there are ambiguous matches.
703 * Each matching type name is decomposed as an array of two strings, the
704 * first denoting the package name (dot-separated) and the second being the
705 * type name. Returns <code>null</code> if unable to find any matching
708 * For example, resolution of <code>"Object"</code> would typically return
709 * <code>{{"java.lang", "Object"}}</code>.
712 * the given type name
713 * @exception JavaModelException
714 * if code resolve could not be performed.
715 * @return the resolved type names or <code>null</code> if unable to find
718 // String[][] resolveType(String typeName) throws JavaModelException;