1a692995afe4485291c8fd25551570b0cea332a2
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / IType.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v0.5 
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v05.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
15 /**
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.
18  * <p>
19  * If a binary type cannot be parsed, its structure remains unknown.
20  * Use <code>IJavaElement.isStructureKnown</code> to determine whether this
21  * is the case.
22  * </p>
23  * <p>
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.
27  * </p>
28  * <p>
29  * This interface is not intended to be implemented by clients.
30  * </p>
31  */
32 public interface IType extends IMember, IParent {
33         /**
34          * Do code completion inside a code snippet in the context of the current type.
35          * 
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.
39          * 
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 
51          * local variables
52          * @param isStatic whether the current scope is in a static context
53          * @param requestor the completion requestor
54          * @since 2.0
55          */
56         void codeComplete(
57                 char[] snippet,
58                 int insertion,
59                 int position,
60                 char[][] localVariableTypeNames,
61                 char[][] localVariableNames,
62                 int[] localVariableModifiers,
63                 boolean isStatic,
64                 ICompletionRequestor requestor)
65                 throws JavaModelException;
66
67         /**
68          * Creates and returns a field in this type with the
69          * given contents.
70          * <p>
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>
74          *
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>
80          * </ul></p>
81          *
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:
87          * <ul>
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)
94          * </ul>
95          * @return a field in this type with the given contents
96          */
97         IField createField(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
98                 throws JavaModelException;
99                 
100         /**
101          * Creates and returns a static initializer in this type with the
102          * given contents.
103          * <p>
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>
108          *
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:
113          * <ul>
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)
119          * </ul>
120          * @return a static initializer in this type with the given contents
121          */
122         IInitializer createInitializer(String contents, IJavaElement sibling, IProgressMonitor monitor)
123                 throws JavaModelException;
124                 
125         /**
126          * Creates and returns a method or constructor in this type with the
127          * given contents.
128          * <p>
129          * Optionally, the new element can be positioned before the specified
130          * sibling. If no sibling is specified, the element will be appended
131          * to this type.
132          *
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>
138          * </ul></p>
139          *
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:
145          * <ul>
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)
153          * </ul>
154          * @return a method or constructor in this type with the given contents
155          */
156         IMethod createMethod(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
157                 throws JavaModelException;
158                 
159         /**
160          * Creates and returns a type in this type with the
161          * given contents.
162          * <p>
163          * Optionally, the new type can be positioned before the specified
164          * sibling. If no sibling is specified, the type will be appended
165          * to this type.
166          *
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>
172          * </ul></p>
173          *
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:
179          * <ul>
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)
186          * </ul>
187          * @return a type in this type with the given contents
188          */
189         IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor)
190                 throws JavaModelException;
191                 
192         /** 
193          * Finds the methods in this type that correspond to
194          * the given method.
195          * A method m1 corresponds to another method m2 if:
196          * <ul>
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.
200          * <li>m1 exists.
201          * </ul>
202          * @param method the given method
203          * @return the found method or <code>null</code> if no such methods can be found.
204          * 
205          * @since 2.0 
206          */
207         IMethod[] findMethods(IMethod method);
208         
209         /**
210          * Returns the simple name of this type, unqualified by package or enclosing type.
211          * This is a handle-only method.
212          * 
213          * @return the simple name of this type
214          */
215         String getElementName();
216         
217         /**
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.
221          * 
222          * @param name the given name
223          * @return the field with the specified name in this type
224          */
225         IField getField(String name);
226         
227         /**
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.
232          *
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
236          */
237         IField[] getFields() throws JavaModelException;
238         
239         /**
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.
245          *
246          * @see IType#getTypeQualifiedName()
247          * @return the fully qualified name of this type
248          */
249         String getFullyQualifiedName();
250         
251         /**
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>.
256          * 
257          * For example:
258          * <ul>
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>
269          * </ul>
270          * 
271          * This is a handle-only method.
272          *
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)
276          * @since 2.0
277          */
278         String getFullyQualifiedName(char enclosingTypeSeparator);
279         
280         /**
281          * Returns the initializer with the specified position relative to
282          * the order they are defined in the source.
283          * Numbering starts at 1 (i.e. the first occurrence is occurrence 1, not occurrence 0).
284          * This is a handle-only method.  The initializer may or may not be present.
285          * 
286          * @param occurrenceCount the specified position
287          * @return the initializer with the specified position relative to the order they are defined in the source
288          */
289         IInitializer getInitializer(int occurrenceCount);
290         
291         /**
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.
296          *
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
300          */
301         IInitializer[] getInitializers() throws JavaModelException;
302         
303         /**
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.
309          * 
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
313          */
314         IMethod getMethod(String name, String[] parameterTypeSignatures);
315         
316         /**
317          * Returns the methods and constructors declared by this type.
318          * For binary types, this may include the special <code>&lt;clinit&gt</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.
323          *
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
327          */
328         IMethod[] getMethods() throws JavaModelException;
329         
330         /**
331          * Returns the package fragment in which this element is defined.
332          * This is a handle-only method.
333          * 
334          * @return the package fragment in which this element is defined
335          */
336         //IPackageFragment getPackageFragment();
337         
338         /**
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.
344          *
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
348          */
349         String getSuperclassName() throws JavaModelException;
350         
351         /**
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, simples name are returned,
358          * for binary types, qualified names are returned.
359          *
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
364          */
365         String[] getSuperInterfaceNames() throws JavaModelException;
366         
367         /**
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.
370          * 
371          * @param the given simple name
372          * @return the member type declared in this type with the given simple name
373          */
374         IType getType(String name);
375         
376         /**
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.
384          * 
385          * @return the type-qualified name of this type
386          */
387         String getTypeQualifiedName();
388         
389         /**
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.
396          * 
397          * For example:
398          * <ul>
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>
409          * </ul>
410          *
411          * This is a handle-only method.
412          * 
413          * @param enclosingTypeSeparator the specified enclosing type separator
414          * @return the type-qualified name of this type
415          * @since 2.0
416          */
417         String getTypeQualifiedName(char enclosingTypeSeparator);
418         
419         /**
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.
422          *
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
426          */
427         IType[] getTypes() throws JavaModelException;
428         
429         /**
430          * Returns whether this type represents an anonymous type.
431          *
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
435          * @since 2.0
436          */
437         boolean isAnonymous() throws JavaModelException;
438
439         /**
440          * Returns whether this type represents a class.
441          *
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
445          */
446         boolean isClass() throws JavaModelException;
447         
448         /**
449          * Returns whether this type represents an interface.
450          *
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
454          */
455         boolean isInterface() throws JavaModelException;
456         
457         /**
458          * Returns whether this type represents a local type.
459          *
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
463          * @since 2.0
464          */
465         boolean isLocal() throws JavaModelException;
466
467         /**
468          * Returns whether this type represents a member type.
469          *
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
473          * @since 2.0
474          */
475         boolean isMember() throws JavaModelException;
476
477         /**
478          * Creates and returns a type hierarchy for this type containing
479          * this type and all of its supertypes.
480          *
481          * @exception JavaModelException if this element does not exist or if an
482          *              exception occurs while accessing its corresponding resource.
483          * @param monitor the given progress monitor
484          * @return a type hierarchy for this type containing this type and all of its supertypes
485          */
486         //ITypeHierarchy newSupertypeHierarchy(IProgressMonitor monitor) throws JavaModelException;
487         
488         /**
489          * Creates and returns a type hierarchy for this type containing
490          * this type and all of its supertypes, considering types in the given 
491          * working copies. In other words, the list of working copies will take 
492          * precedence over their original compilation units in the workspace.
493          * <p>
494          * Note that passing an empty working copy will be as if the original compilation
495          * unit had been deleted.
496          *
497          * @param workingCopies the working copies that take precedence over their original compilation units
498          * @param monitor the given progress monitor
499          * @return a type hierarchy for this type containing this type and all of its supertypes
500          * @exception JavaModelException if this element does not exist or if an
501          *              exception occurs while accessing its corresponding resource.
502          * @since 2.0
503          */
504 //      ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[] workingCopies, IProgressMonitor monitor)
505 //              throws JavaModelException;
506 //              
507         /**
508          * Creates and returns a type hierarchy for this type containing
509          * this type, all of its supertypes, and all its subtypes in the workspace.
510          *
511          * @exception JavaModelException if this element does not exist or if an
512          *              exception occurs while accessing its corresponding resource.
513          * @param monitor the given progress monitor
514          * @return a type hierarchy for this type containing
515          * this type, all of its supertypes, and all its subtypes in the workspace
516          */
517 //      ITypeHierarchy newTypeHierarchy(IProgressMonitor monitor) throws JavaModelException;
518         
519         /**
520          * Creates and returns a type hierarchy for this type containing
521          * this type, all of its supertypes, and all its subtypes in the workspace, 
522          * considering types in the given working copies. In other words, the list of working 
523          * copies that will take precedence over their original compilation units in the workspace.
524          * <p>
525          * Note that passing an empty working copy will be as if the original compilation
526          * unit had been deleted.
527          *
528          * @param workingCopies the working copies that take precedence over their original compilation units
529          * @param monitor the given progress monitor
530          * @return a type hierarchy for this type containing
531          * this type, all of its supertypes, and all its subtypes in the workspace
532          * @exception JavaModelException if this element does not exist or if an
533          *              exception occurs while accessing its corresponding resource.
534          * @since 2.0
535          */
536         // ITypeHierarchy newTypeHierarchy(IWorkingCopy[] workingCopies, IProgressMonitor monitor) throws JavaModelException;
537         
538         /**
539          * Creates and returns a type hierarchy for this type containing
540          * this type, all of its supertypes, and all its subtypes 
541          * in the context of the given project.
542          *
543          * @param project the given project
544          * @param monitor the given progress monitor
545          * @exception JavaModelException if this element does not exist or if an
546          *              exception occurs while accessing its corresponding resource.
547          * @return a type hierarchy for this type containing
548          * this type, all of its supertypes, and all its subtypes 
549          * in the context of the given project
550          */
551 //      ITypeHierarchy newTypeHierarchy(IJavaProject project, IProgressMonitor monitor) throws JavaModelException;
552         
553         /**
554          * Resolves the given type name within the context of this type (depending on the type hierarchy 
555          * and its imports). Multiple answers might be found in case there are ambiguous matches.
556          *
557          * Each matching type name is decomposed as an array of two strings, the first denoting the package
558          * name (dot-separated) and the second being the type name.
559          * Returns <code>null</code> if unable to find any matching type.
560          *
561          * For example, resolution of <code>"Object"</code> would typically return
562          * <code>{{"java.lang", "Object"}}</code>.
563          * 
564          * @param typeName the given type name
565          * @exception JavaModelException if code resolve could not be performed. 
566          * @return the resolved type names or <code>null</code> if unable to find any matching type
567          */
568         String[][] resolveType(String typeName) throws JavaModelException;
569 }