Statement.java

/*******************************************************************************
 * Copyright (c) 2000, 2013 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.jdt.core.dom;

import org.eclipse.jdt.core.compiler.InvalidInputException;
import org.eclipse.jdt.internal.compiler.parser.Scanner;
import org.eclipse.jdt.internal.compiler.parser.TerminalTokens;

/**
 * Abstract base class of AST nodes that represent statements.
 * There are many kinds of statements.
 * <p>
 * The grammar combines both Statement and BlockStatement.</p>
 * <pre>
 * Statement:
 *    {@link AssertStatement},
 *    {@link Block},
 *    {@link BreakStatement},
 *    {@link ConstructorInvocation},
 *    {@link ContinueStatement},
 *    {@link DoStatement},
 *    {@link EmptyStatement},
 *    {@link EnhancedForStatement}
 *    {@link ExpressionStatement},
 *    {@link ForStatement},
 *    {@link IfStatement},
 *    {@link LabeledStatement},
 *    {@link ReturnStatement},
 *    {@link SuperConstructorInvocation},
 *    {@link SwitchCase},
 *    {@link SwitchStatement},
 *    {@link SynchronizedStatement},
 *    {@link ThrowStatement},
 *    {@link TryStatement},
 *    {@link TypeDeclarationStatement},
 *    {@link VariableDeclarationStatement},
 *    {@link WhileStatement}
 * </pre>
 *
 * @since 2.0
 */
public abstract class Statement extends ASTNode {

	/**
	 * The leading comment, or <code>null</code> if none.
	 * Defaults to none.
	 *
	 * @deprecated The leading comment feature was removed in 2.1.
	 */
	private String optionalLeadingComment = null;

	/**
	 * Creates a new AST node for a statement owned by the given AST.
	 * <p>
	 * N.B. This constructor is package-private.
	 * </p>
	 *
	 * @param ast the AST that is to own this node
	 */
	Statement(AST ast) {
		super(ast);
	}

	/**
	 * Returns the leading comment string, including the starting
	 * and ending comment delimiters, and any embedded line breaks.
	 * <p>
	 * A leading comment is a comment that appears before the statement.
	 * It may be either a traditional comment or an end-of-line comment.
	 * Traditional comments must begin with "/*, may contain line breaks,
	 * and must end with "*/. End-of-line comments must begin with "//",
	 * must end with a line delimiter (as per JLS 3.7), and must not contain
	 * line breaks.
	 * </p>
	 *
	 * @return the comment string, or <code>null</code> if none
	 * @deprecated This feature was removed in the 2.1 release because it was
	 * only a partial, and inadequate, solution to the issue of associating
	 * comments with statements. Furthermore, AST.parseCompilationUnit did not
	 * associate leading comments, making this moot. Clients that need to access
	 * comments preceding a statement should either consult the compilation
	 * unit's {@linkplain CompilationUnit#getCommentList() comment table}
	 * or use a scanner to reanalyze the source text immediately preceding
	 * the statement's source range.
	 */
	public String getLeadingComment() {
		return this.optionalLeadingComment;
	}

	/**
	 * Sets or clears the leading comment string. The comment
	 * string must include the starting and ending comment delimiters,
	 * and any embedded linebreaks.
	 * <p>
	 * A leading comment is a comment that appears before the statement.
	 * It may be either a traditional comment or an end-of-line comment.
	 * Traditional comments must begin with "/*, may contain line breaks,
	 * and must end with "*/. End-of-line comments must begin with "//"
	 * (as per JLS 3.7), and must not contain line breaks.
	 * </p>
	 * <p>
	 * Examples:
	 * <code>
	 * <pre>
	 * setLeadingComment("/* traditional comment */");  // correct
	 * setLeadingComment("missing comment delimiters");  // wrong
	 * setLeadingComment("/* unterminated traditional comment ");  // wrong
	 * setLeadingComment("/* broken\n traditional comment */");  // correct
	 * setLeadingComment("// end-of-line comment\n");  // correct
	 * setLeadingComment("// end-of-line comment without line terminator");  // correct
	 * setLeadingComment("// broken\n end-of-line comment\n");  // wrong
	 * </pre>
	 * </code>
	 * </p>
	 *
	 * @param comment the comment string, or <code>null</code> if none
	 * @exception IllegalArgumentException if the comment string is invalid
	 * @deprecated This feature was removed in the 2.1 release because it was
	 * only a partial, and inadequate, solution to the issue of associating
	 * comments with statements.
	 */
	public void setLeadingComment(String comment) {
		if (comment != null) {
			char[] source = comment.toCharArray();
			Scanner scanner = this.ast.scanner;
			scanner.resetTo(0, source.length);
			scanner.setSource(source);
			try {
				int token;
				boolean onlyOneComment = false;
				while ((token = scanner.getNextToken()) != TerminalTokens.TokenNameEOF) {
					switch(token) {
						case TerminalTokens.TokenNameCOMMENT_BLOCK :
						case TerminalTokens.TokenNameCOMMENT_JAVADOC :
						case TerminalTokens.TokenNameCOMMENT_LINE :
							if (onlyOneComment) {
								throw new IllegalArgumentException();
							}
							onlyOneComment = true;
							break;
						default:
							onlyOneComment = false;
					}
				}
				if (!onlyOneComment) {
					throw new IllegalArgumentException();
				}
			} catch (InvalidInputException e) {
				throw new IllegalArgumentException(e);
			}
		}
		// we do not consider the obsolete comment as a structureal property
		// but we protect them nevertheless
		checkModifiable();
		this.optionalLeadingComment = comment;
	}

	/**
	 * Copies the leading comment from the given statement.
	 *
	 * @param source the statement that supplies the leading comment
	 * @since 2.1
	 */
	void copyLeadingComment(Statement source) {
		setLeadingComment(source.getLeadingComment());
	}

	/* (omit javadoc for this method)
	 * Method declared on ASTNode.
	 */
	int memSize() {
		int size = BASE_NODE_SIZE + 1 * 4 + stringSize(getLeadingComment());
		return size;
	}
}