KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > dom > Statement


1 /*******************************************************************************
2  * Copyright (c) 2000, 2004 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11
12 package org.eclipse.jdt.core.dom;
13
14 import org.eclipse.jdt.core.compiler.InvalidInputException;
15 import org.eclipse.jdt.internal.compiler.parser.Scanner;
16 import org.eclipse.jdt.internal.compiler.parser.TerminalTokens;
17
18 /**
19  * Abstract base class of AST nodes that represent statements.
20  * There are many kinds of statements.
21  * <p>
22  * The grammar combines both Statement and BlockStatement.
23  * For JLS2:
24  * <pre>
25  * Statement:
26  * Block
27  * IfStatement
28  * ForStatement
29  * WhileStatement
30  * DoStatement
31  * TryStatement
32  * SwitchStatement
33  * SynchronizedStatement
34  * ReturnStatement
35  * ThrowStatement
36  * BreakStatement
37  * ContinueStatement
38  * EmptyStatement
39  * ExpressionStatement
40  * LabeledStatement
41  * AssertStatement
42  * VariableDeclarationStatement
43  * TypeDeclarationStatement
44  * ConstructorInvocation
45  * SuperConstructorInvocation
46  * </pre>
47  * For JLS3, an enhanced for node type was added:
48  * <pre>
49  * Statement:
50  * Block
51  * IfStatement
52  * ForStatement
53  * EnhancedForStatement
54  * WhileStatement
55  * DoStatement
56  * TryStatement
57  * SwitchStatement
58  * SynchronizedStatement
59  * ReturnStatement
60  * ThrowStatement
61  * BreakStatement
62  * ContinueStatement
63  * EmptyStatement
64  * ExpressionStatement
65  * LabeledStatement
66  * AssertStatement
67  * VariableDeclarationStatement
68  * TypeDeclarationStatement
69  * ConstructorInvocation
70  * SuperConstructorInvocation
71  * </pre>
72  * </p>
73  *
74  * @since 2.0
75  */
76 public abstract class Statement extends ASTNode {
77     
78     /**
79      * The leading comment, or <code>null</code> if none.
80      * Defaults to none.
81      *
82      * @deprecated The leading comment feature was removed in 2.1.
83      */
84     private String JavaDoc optionalLeadingComment = null;
85     
86     /**
87      * Creates a new AST node for a statement owned by the given AST.
88      * <p>
89      * N.B. This constructor is package-private.
90      * </p>
91      *
92      * @param ast the AST that is to own this node
93      */
94     Statement(AST ast) {
95         super(ast);
96     }
97     
98     /**
99      * Returns the leading comment string, including the starting
100      * and ending comment delimiters, and any embedded line breaks.
101      * <p>
102      * A leading comment is a comment that appears before the statement.
103      * It may be either a traditional comment or an end-of-line comment.
104      * Traditional comments must begin with "/&#42;, may contain line breaks,
105      * and must end with "&#42;/. End-of-line comments must begin with "//",
106      * must end with a line delimiter (as per JLS 3.7), and must not contain
107      * line breaks.
108      * </p>
109      *
110      * @return the comment string, or <code>null</code> if none
111      * @deprecated This feature was removed in the 2.1 release because it was
112      * only a partial, and inadequate, solution to the issue of associating
113      * comments with statements. Furthermore, AST.parseCompilationUnit did not
114      * associate leading comments, making this moot. Clients that need to access
115      * comments preceding a statement should either consult the compilation
116      * unit's {@linkplain CompilationUnit#getCommentList() comment table}
117      * or use a scanner to reanalyze the source text immediately preceding
118      * the statement's source range.
119      */
120     public String JavaDoc getLeadingComment() {
121         return optionalLeadingComment;
122     }
123
124     /**
125      * Sets or clears the leading comment string. The comment
126      * string must include the starting and ending comment delimiters,
127      * and any embedded linebreaks.
128      * <p>
129      * A leading comment is a comment that appears before the statement.
130      * It may be either a traditional comment or an end-of-line comment.
131      * Traditional comments must begin with "/&#42;, may contain line breaks,
132      * and must end with "&#42;/. End-of-line comments must begin with "//"
133      * (as per JLS 3.7), and must not contain line breaks.
134      * </p>
135      * <p>
136      * Examples:
137      * <code>
138      * <pre>
139      * setLeadingComment("/&#42; traditional comment &#42;/"); // correct
140      * setLeadingComment("missing comment delimiters"); // wrong
141      * setLeadingComment("/&#42; unterminated traditional comment "); // wrong
142      * setLeadingComment("/&#42; broken\n traditional comment &#42;/"); // correct
143      * setLeadingComment("// end-of-line comment\n"); // correct
144      * setLeadingComment("// end-of-line comment without line terminator"); // correct
145      * setLeadingComment("// broken\n end-of-line comment\n"); // wrong
146      * </pre>
147      * </code>
148      * </p>
149      *
150      * @param comment the comment string, or <code>null</code> if none
151      * @exception IllegalArgumentException if the comment string is invalid
152      * @deprecated This feature was removed in the 2.1 release because it was
153      * only a partial, and inadequate, solution to the issue of associating
154      * comments with statements.
155      */
156     public void setLeadingComment(String JavaDoc comment) {
157         if (comment != null) {
158             char[] source = comment.toCharArray();
159             Scanner scanner = this.ast.scanner;
160             scanner.resetTo(0, source.length);
161             scanner.setSource(source);
162             try {
163                 int token;
164                 boolean onlyOneComment = false;
165                 while ((token = scanner.getNextToken()) != TerminalTokens.TokenNameEOF) {
166                     switch(token) {
167                         case TerminalTokens.TokenNameCOMMENT_BLOCK :
168                         case TerminalTokens.TokenNameCOMMENT_JAVADOC :
169                         case TerminalTokens.TokenNameCOMMENT_LINE :
170                             if (onlyOneComment) {
171                                 throw new IllegalArgumentException JavaDoc();
172                             }
173                             onlyOneComment = true;
174                             break;
175                         default:
176                             onlyOneComment = false;
177                     }
178                 }
179                 if (!onlyOneComment) {
180                     throw new IllegalArgumentException JavaDoc();
181                 }
182             } catch (InvalidInputException e) {
183                 throw new IllegalArgumentException JavaDoc();
184             }
185         }
186         // we do not consider the obsolete comment as a structureal property
187 // but we protect them nevertheless
188 checkModifiable();
189         this.optionalLeadingComment = comment;
190     }
191
192     /**
193      * Copies the leading comment from the given statement.
194      *
195      * @param source the statement that supplies the leading comment
196      * @since 2.1
197      */
198     void copyLeadingComment(Statement source) {
199         setLeadingComment(source.getLeadingComment());
200     }
201     
202     /* (omit javadoc for this method)
203      * Method declared on ASTNode.
204      */
205     int memSize() {
206         int size = BASE_NODE_SIZE + 1 * 4 + stringSize(getLeadingComment());
207         return size;
208     }
209 }
210
211
Popular Tags