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