Documentation update from php.net
[phpeclipse.git] / 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 }