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 }