net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/internal/compiler/IDocumentElementRequestor.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.internal.compiler;
  12
  13 import net.sourceforge.phpdt.core.compiler.IProblem;
  14
  15 /**
  16  * Part of the source element parser responsible for building the output. It
  17  * gets notified of structural information as they are detected, relying on the
  18  * requestor to assemble them together, based on the notifications it got.
  19  *
  20  * The structural investigation includes: - package statement - import
  21  * statements - top-level types: package member, member types (member types of
  22  * member types...) - fields - methods
  23  *
  24  * If reference information is requested, then all source constructs are
  25  * investigated and type, field & method references are provided as well.
  26  *
  27  * Any (parsing) problem encountered is also provided.
  28  *
  29  * All positions are relative to the exact source fed to the parser.
  30  *
  31  * Elements which are complex are notified in two steps: - enter<Element> :
  32  * once the element header has been identified - exit<Element> : once the
  33  * element has been fully consumed
  34  *
  35  * other simpler elements (package, import) are read all at once: - accept<Element>
  36  */
  37
  38 public interface IDocumentElementRequestor {
  39         /**
  40          * @param declarationStart -
  41          *            a source position corresponding to the start of the package
  42          *            declaration
  43          * @param declarationEnd -
  44          *            a source position corresponding to the end of the package
  45          *            declaration
  46          * @param javaDocPositions -
  47          *            answer back an array of sourceStart/sourceEnd positions of the
  48          *            available JavaDoc comments. The array is a flattened
  49          *            structure: 2*n entries with consecutives start and end
  50          *            positions. If no JavaDoc is available, then null is answered
  51          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
  52          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
  53          *            equals to null if there are no javadoc comments
  54          * @param name -
  55          *            the name of the package
  56          * @param nameStartPosition -
  57          *            a source position corresponding to the first character of the
  58          *            name
  59          * @param onDemand -
  60          *            a boolean equals to true if the import is an import on demand
  61          */
  62         void acceptImport(int declarationStart, int declarationEnd,
  63                         int[] javaDocPositions, char[] name, int nameStartPosition,
  64                         boolean onDemand);
  65
  66         /**
  67          * @param declarationStart -
  68          *            a source position corresponding to the start of the package
  69          *            declaration
  70          * @param declarationEnd -
  71          *            a source position corresponding to the end of the package
  72          *            declaration
  73          * @param javaDocPositions -
  74          *            answer back an array of sourceStart/sourceEnd positions of the
  75          *            available JavaDoc comments. The array is a flattened
  76          *            structure: 2*n entries with consecutives start and end
  77          *            positions. If no JavaDoc is available, then null is answered
  78          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
  79          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
  80          *            equals to null if there are no javadoc comments
  81          * @param modifiers -
  82          *            the modifiers for this initializer
  83          * @param modifiersStart -
  84          *            a source position corresponding to the start of the textual
  85          *            modifiers, is < 0 if there are no textual modifiers
  86          * @param bodyStart -
  87          *            the position of the '{'
  88          * @param bodyEnd -
  89          *            the position of the '}'
  90          */
  91         void acceptInitializer(int declarationStart, int declarationEnd,
  92                         int[] javaDocPositions, int modifiers, int modifiersStart,
  93                         int bodyStart, int bodyEnd);
  94
  95         /*
  96          * Table of line separator position. This table is passed once at the end of
  97          * the parse action, so as to allow computation of normalized ranges.
  98          *
  99          * A line separator might corresponds to several characters in the source,
 100          *
 101          */
 102         void acceptLineSeparatorPositions(int[] positions);
 103
 104         /**
 105          * @param declarationStart -
 106          *            a source position corresponding to the start of the package
 107          *            declaration
 108          * @param declarationEnd -
 109          *            a source position corresponding to the end of the package
 110          *            declaration
 111          * @param javaDocPositions -
 112          *            answer back an array of sourceStart/sourceEnd positions of the
 113          *            available JavaDoc comments. The array is a flattened
 114          *            structure: 2*n entries with consecutives start and end
 115          *            positions. If no JavaDoc is available, then null is answered
 116          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 117          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 118          *            equals to null if there are no javadoc comments
 119          * @param name -
 120          *            the name of the package
 121          * @param nameStartPosition -
 122          *            a source position corresponding to the first character of the
 123          *            name
 124          */
 125         void acceptPackage(int declarationStart, int declarationEnd,
 126                         int[] javaDocPositions, char[] name, int nameStartPosition);
 127
 128         /**
 129          * @param problem -
 130          *            Used to report a problem while running the JDOM
 131          */
 132         void acceptProblem(IProblem problem);
 133
 134         /**
 135          * @param declarationStart -
 136          *            a source position corresponding to the start of this class.
 137          * @param javaDocPositions -
 138          *            answer back an array of sourceStart/sourceEnd positions of the
 139          *            available JavaDoc comments. The array is a flattened
 140          *            structure: 2*n entries with consecutives start and end
 141          *            positions. If no JavaDoc is available, then null is answered
 142          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 143          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 144          *            equals to null if there are no javadoc comments
 145          * @param modifiers -
 146          *            the modifiers for this class
 147          * @param modifiersStart -
 148          *            a source position corresponding to the start of the textual
 149          *            modifiers, is < 0 if there are no textual modifiers
 150          * @param classStart -
 151          *            a source position corresponding to the start of the keyword
 152          *            'class'
 153          * @param name -
 154          *            the name of the class
 155          * @param nameStart -
 156          *            a source position corresponding to the start of the name
 157          * @param nameEnd -
 158          *            a source position corresponding to the end of the name
 159          * @param superclass -
 160          *            the name of the superclass
 161          * @param superclassStart -
 162          *            a source position corresponding to the start of the superclass
 163          *            name
 164          * @param superclassEnd -
 165          *            a source position corresponding to the end of the superclass
 166          *            name
 167          * @param superinterfaces -
 168          *            the name of the superinterfaces
 169          * @param superinterfaceStarts -
 170          *            an array of source positions corresponding to the start of
 171          *            their respective superinterface names
 172          * @param superinterfaceEnds -
 173          *            an array of source positions corresponding to the end of their
 174          *            respective superinterface names
 175          * @param bodyStart -
 176          *            a source position corresponding to the open bracket of the
 177          *            class body
 178          */
 179         void enterClass(int declarationStart, int[] javaDocPositions,
 180                         int modifiers, int modifiersStart, int classStart, char[] name,
 181                         int nameStart, int nameEnd, char[] superclass, int superclassStart,
 182                         int superclassEnd, char[][] superinterfaces,
 183                         int[] superinterfaceStarts, int[] superinterfaceEnds, int bodyStart);
 184
 185         void enterCompilationUnit();
 186
 187         /**
 188          * @param declarationStart -
 189          *            a source position corresponding to the first character of this
 190          *            constructor declaration
 191          * @param javaDocPositions -
 192          *            answer back an array of sourceStart/sourceEnd positions of the
 193          *            available JavaDoc comments. The array is a flattened
 194          *            structure: 2*n entries with consecutives start and end
 195          *            positions. If no JavaDoc is available, then null is answered
 196          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 197          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 198          *            equals to null if there are no javadoc comments
 199          * @param modifiers -
 200          *            the modifiers for this constructor converted to a flag
 201          * @param modifiersStart -
 202          *            a source position corresponding to the first character of the
 203          *            textual modifiers
 204          * @param name -
 205          *            the name of this constructor
 206          * @param nameStart -
 207          *            a source position corresponding to the first character of the
 208          *            name
 209          * @param nameEnd -
 210          *            a source position corresponding to the last character of the
 211          *            name
 212          * @param parameterTypes -
 213          *            a list of parameter type names
 214          * @param parameterTypeStarts -
 215          *            a list of source positions corresponding to the first
 216          *            character of each parameter type name
 217          * @param parameterTypeEnds -
 218          *            a list of source positions corresponding to the last character
 219          *            of each parameter type name
 220          * @param parameterNames -
 221          *            a list of the names of the parameters
 222          * @param parametersEnd -
 223          *            a source position corresponding to the last character of the
 224          *            parameter list
 225          * @param exceptionTypes -
 226          *            a list of the exception types
 227          * @param exceptionTypeStarts -
 228          *            a list of source positions corresponding to the first
 229          *            character of the respective exception types
 230          * @param exceptionTypeEnds -
 231          *            a list of source positions corresponding to the last character
 232          *            of the respective exception types
 233          * @param bodyStart -
 234          *            a source position corresponding to the start of this
 235          *            constructor's body
 236          */
 237         void enterConstructor(int declarationStart, int[] javaDocPositions,
 238                         int modifiers, int modifiersStart, char[] name, int nameStart,
 239                         int nameEnd, char[][] parameterTypes, int[] parameterTypeStarts,
 240                         int[] parameterTypeEnds, char[][] parameterNames,
 241                         int[] parameterNameStarts, int[] parameterNameEnds,
 242                         int parametersEnd, char[][] exceptionTypes,
 243                         int[] exceptionTypeStarts, int[] exceptionTypeEnds, int bodyStart);
 244
 245         /**
 246          * @param declarationStart -
 247          *            a source position corresponding to the first character of this
 248          *            field
 249          * @param javaDocPositions -
 250          *            answer back an array of sourceStart/sourceEnd positions of the
 251          *            available JavaDoc comments. The array is a flattened
 252          *            structure: 2*n entries with consecutives start and end
 253          *            positions. If no JavaDoc is available, then null is answered
 254          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 255          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 256          *            equals to null if there are no javadoc comments
 257          * @param modifiers -
 258          *            the modifiers for this field converted to a flag
 259          * @param modifiersStart -
 260          *            a source position corresponding to the first character of the
 261          *            textual modifiers
 262          * @param type -
 263          *            the name of the field type
 264          * @param typeStart -
 265          *            a source position corresponding to the start of the fields
 266          *            type
 267          * @param typeEnd -
 268          *            a source position corresponding to the end of the fields type
 269          * @param typeDimensionCount -
 270          *            the array dimension indicated on the type (for example, 'int[]
 271          *            v')
 272          * @param name -
 273          *            the name of this constructor
 274          * @param nameStart -
 275          *            a source position corresponding to the first character of the
 276          *            name
 277          * @param nameEnd -
 278          *            a source position corresponding to the last character of the
 279          *            name
 280          * @param extendedTypeDimensionCount -
 281          *            the array dimension indicated on the variable, (for example,
 282          *            'int v[]')
 283          * @param extendedTypeDimnesionEnd -
 284          *            a source position corresponding to the end of the extened type
 285          *            dimension. This position should be -1 in case there is no
 286          *            extended dimension for the type.
 287          */
 288         void enterField(int declarationStart, int[] javaDocPositions,
 289                         int modifiers, int modifiersStart, char[] type, int typeStart,
 290                         int typeEnd, int typeDimensionCount, char[] name, int nameStart,
 291                         int nameEnd, int extendedTypeDimensionCount,
 292                         int extendedTypeDimensionEnd);
 293
 294         /**
 295          * @param declarationStart -
 296          *            a source position corresponding to the start of this class.
 297          * @param javaDocPositions -
 298          *            answer back an array of sourceStart/sourceEnd positions of the
 299          *            available JavaDoc comments. The array is a flattened
 300          *            structure: 2*n entries with consecutives start and end
 301          *            positions. If no JavaDoc is available, then null is answered
 302          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 303          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 304          *            equals to null if there are no javadoc comments
 305          * @param modifiers -
 306          *            the modifiers for this class
 307          * @param modifiersStart -
 308          *            a source position corresponding to the start of the textual
 309          *            modifiers, is < 0 if there are no textual modifiers
 310          * @param interfaceStart -
 311          *            a source position corresponding to the start of the keyword
 312          *            'interface'
 313          * @param name -
 314          *            the name of the class
 315          * @param nameStart -
 316          *            a source position corresponding to the start of the name
 317          * @param nameEnd -
 318          *            a source position corresponding to the end of the name
 319          * @param superinterfaces -
 320          *            the name of the superinterfaces
 321          * @param superinterfaceStarts -
 322          *            an array of source positions corresponding to the start of
 323          *            their respective superinterface names
 324          * @param superinterfaceEnds -
 325          *            an array of source positions corresponding to the end of their
 326          *            respective superinterface names
 327          * @param bodyStart -
 328          *            a source position corresponding to the open bracket of the
 329          *            class body
 330          */
 331         void enterInterface(int declarationStart, int[] javaDocPositions,
 332                         int modifiers, int modifiersStart, int interfaceStart, char[] name,
 333                         int nameStart, int nameEnd, char[][] superinterfaces,
 334                         int[] superinterfaceStarts, int[] superinterfaceEnds, int bodyStart);
 335
 336         /**
 337          * @param declarationStart -
 338          *            a source position corresponding to the first character of this
 339          *            constructor declaration
 340          * @param javaDocPositions -
 341          *            answer back an array of sourceStart/sourceEnd positions of the
 342          *            available JavaDoc comments. The array is a flattened
 343          *            structure: 2*n entries with consecutives start and end
 344          *            positions. If no JavaDoc is available, then null is answered
 345          *            instead of an empty array. e.g. { 10, 20, 25, 45 } -->
 346          *            javadoc1 from 10 to 20, javadoc2 from 25 to 45 The array is
 347          *            equals to null if there are no javadoc comments
 348          * @param modifiers -
 349          *            the modifiers for this constructor converted to a flag
 350          * @param modifiersStart -
 351          *            a source position corresponding to the first character of the
 352          *            textual modifiers
 353          * @param returnType -
 354          *            the name of the return type
 355          * @param returnTypeStart -
 356          *            a source position corresponding to the first character of the
 357          *            return type
 358          * @param returnTypeEnd -
 359          *            a source position corresponding to the last character of the
 360          *            return type
 361          * @param returnTypeDimensionCount -
 362          *            the array dimension count as supplied on the return type (for
 363          *            example, 'public int[] foo() {}')
 364          * @param name -
 365          *            the name of this constructor
 366          * @param nameStart -
 367          *            a source position corresponding to the first character of the
 368          *            name
 369          * @param nameEnd -
 370          *            a source position corresponding to the last character of the
 371          *            name
 372          * @param parameterTypes -
 373          *            a list of parameter type names
 374          * @param parameterTypeStarts -
 375          *            a list of source positions corresponding to the first
 376          *            character of each parameter type name
 377          * @param parameterTypeEnds -
 378          *            a list of source positions corresponding to the last character
 379          *            of each parameter type name
 380          * @param parameterNames -
 381          *            a list of the names of the parameters
 382          * @param parametersEnd -
 383          *            a source position corresponding to the last character of the
 384          *            parameter list
 385          * @param extendedReturnTypeDimensionCount -
 386          *            the array dimension count as supplied on the end of the
 387          *            parameter list (for example, 'public int foo()[] {}')
 388          * @param extendedReturnTypeDimensionEnd -
 389          *            a source position corresponding to the last character of the
 390          *            extended return type dimension. This position should be -1 in
 391          *            case there is no extended dimension for the type.
 392          * @param exceptionTypes -
 393          *            a list of the exception types
 394          * @param exceptionTypeStarts -
 395          *            a list of source positions corresponding to the first
 396          *            character of the respective exception types
 397          * @param exceptionTypeEnds -
 398          *            a list of source positions corresponding to the last character
 399          *            of the respective exception types
 400          * @param bodyStart -
 401          *            a source position corresponding to the start of this method's
 402          *            body
 403          */
 404         void enterMethod(int declarationStart, int[] javaDocPositions,
 405                         int modifiers, int modifiersStart, char[] returnType,
 406                         int returnTypeStart, int returnTypeEnd,
 407                         int returnTypeDimensionCount, char[] name, int nameStart,
 408                         int nameEnd, char[][] parameterTypes, int[] parameterTypeStarts,
 409                         int[] parameterTypeEnds, char[][] parameterNames,
 410                         int[] parameterNameStarts, int[] parameterNameEnds,
 411                         int parametersEnd, int extendedReturnTypeDimensionCount,
 412                         int extendedReturnTypeDimensionEnd, char[][] exceptionTypes,
 413                         int[] exceptionTypeStarts, int[] exceptionTypeEnds, int bodyStart);
 414
 415         /**
 416          * @param bodyEnd -
 417          *            a source position corresponding to the closing bracket of the
 418          *            class
 419          * @param declarationEnd -
 420          *            a source position corresponding to the end of the class
 421          *            declaration. This can include whitespace and comments
 422          *            following the closing bracket.
 423          */
 424         void exitClass(int bodyEnd, int declarationEnd);
 425
 426         /**
 427          * @param declarationEnd -
 428          *            a source position corresponding to the end of the compilation
 429          *            unit
 430          */
 431         void exitCompilationUnit(int declarationEnd);
 432
 433         /**
 434          * @param bodyEnd -
 435          *            a source position corresponding to the closing bracket of the
 436          *            method
 437          * @param declarationEnd -
 438          *            a source position corresponding to the end of the method
 439          *            declaration. This can include whitespace and comments
 440          *            following the closing bracket.
 441          */
 442         void exitConstructor(int bodyEnd, int declarationEnd);
 443
 444         /**
 445          * @param bodyEnd -
 446          *            a source position corresponding to the end of the field.
 447          * @param declarationEnd -
 448          *            a source position corresponding to the end of the field. This
 449          *            can include whitespace and comments following the semi-colon.
 450          */
 451         void exitField(int bodyEnd, int declarationEnd);
 452
 453         /**
 454          * @param bodyEnd -
 455          *            a source position corresponding to the closing bracket of the
 456          *            interface
 457          * @param declarationEnd -
 458          *            a source position corresponding to the end of the interface
 459          *            declaration. This can include whitespace and comments
 460          *            following the closing bracket.
 461          */
 462         void exitInterface(int bodyEnd, int declarationEnd);
 463
 464         /**
 465          * @param bodyEnd -
 466          *            a source position corresponding to the closing bracket of the
 467          *            method
 468          * @param declarationEnd -
 469          *            a source position corresponding to the end of the method
 470          *            declaration. This can include whitespace and comments
 471          *            following the closing bracket.
 472          */
 473         void exitMethod(int bodyEnd, int declarationEnd);
 474 }