net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/CompilationUnit.java

   1 package net.sourceforge.phpdt.core.dom;
   2 /*******************************************************************************
   3  * Copyright (c) 2000, 2004 IBM Corporation and others.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Common Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/cpl-v10.html
   8  *
   9  * Contributors:
  10  *     IBM Corporation - initial API and implementation
  11  *******************************************************************************/
  12
  13
  14 /**
  15  * Java compilation unit AST node type. This is the type of the root of an AST.
  16  * <p>
  17  * The source range for this type of node is ordinarily the entire source file,
  18  * including leading and trailing whitespace and comments.
  19  * </p>
  20  * For JLS2:
  21  * <pre>
  22  * CompilationUnit:
  23  *    [ PackageDeclaration ]
  24  *        { ImportDeclaration }
  25  *        { TypeDeclaration | <b>;</b> }
  26  * </pre>
  27  * For JLS3, the kinds of type declarations
  28  * grew to include enum and annotation type declarations:
  29  * <pre>
  30  * CompilationUnit:
  31  *    [ PackageDeclaration ]
  32  *        { ImportDeclaration }
  33  *        { TypeDeclaration | EnumDeclaration | AnnotationTypeDeclaration | <b>;</b> }
  34  * </pre>
  35  *
  36  * @since 2.0
  37  */
  38 public class CompilationUnit {
  39
  40 //      /**
  41 //       * The "package" structural property of this node type.
  42 //       *
  43 //       * @since 3.0
  44 //       */
  45 //      public static final ChildPropertyDescriptor PACKAGE_PROPERTY =
  46 //              new ChildPropertyDescriptor(CompilationUnit.class, "package", PackageDeclaration.class, OPTIONAL, NO_CYCLE_RISK); //$NON-NLS-1$
  47 //
  48 //      /**
  49 //       * The "imports" structural property of this node type.
  50 //       *
  51 //       * @since 3.0
  52 //       */
  53 //      public static final ChildListPropertyDescriptor IMPORTS_PROPERTY =
  54 //              new ChildListPropertyDescriptor(CompilationUnit.class, "imports", ImportDeclaration.class, NO_CYCLE_RISK); //$NON-NLS-1$
  55 //
  56 //      /**
  57 //       * The "types" structural property of this node type.
  58 //       *
  59 //       * @since 3.0
  60 //       */
  61 //      public static final ChildListPropertyDescriptor TYPES_PROPERTY =
  62 //              new ChildListPropertyDescriptor(CompilationUnit.class, "types", AbstractTypeDeclaration.class, CYCLE_RISK); //$NON-NLS-1$
  63 //
  64 //      /**
  65 //       * A list of property descriptors (element type:
  66 //       * {@link StructuralPropertyDescriptor}),
  67 //       * or null if uninitialized.
  68 //       * @since 3.0
  69 //       */
  70 //      private static final List PROPERTY_DESCRIPTORS;
  71 //
  72 //      static {
  73 //              createPropertyList(CompilationUnit.class);
  74 //              addProperty(PACKAGE_PROPERTY);
  75 //              addProperty(IMPORTS_PROPERTY);
  76 //              addProperty(TYPES_PROPERTY);
  77 //              PROPERTY_DESCRIPTORS = reapPropertyList();
  78 //      }
  79 //
  80 //      /**
  81 //       * Returns a list of structural property descriptors for this node type.
  82 //       * Clients must not modify the result.
  83 //       *
  84 //       * @param apiLevel the API level; one of the
  85 //       * <code>AST.JLS&ast;</code> constants
  86 //
  87 //       * @return a list of property descriptors (element type:
  88 //       * {@link StructuralPropertyDescriptor})
  89 //       * @since 3.0
  90 //       */
  91 //      public static List propertyDescriptors(int apiLevel) {
  92 //              return PROPERTY_DESCRIPTORS;
  93 //      }
  94 //
  95 //      /**
  96 //       * The comment table, or <code>null</code> if none; initially
  97 //       * <code>null</code>. This array is the storage underlying
  98 //       * the <code>optionalCommentList</code> ArrayList.
  99 //       * @since 3.0
 100 //       */
 101 //      Comment[] optionalCommentTable = null;
 102 //
 103 //      /**
 104 //       * The comment list (element type: <code>Comment</code>,
 105 //       * or <code>null</code> if none; initially <code>null</code>.
 106 //       * @since 3.0
 107 //       */
 108 //      private List optionalCommentList = null;
 109 //
 110 //      /**
 111 //       * The package declaration, or <code>null</code> if none; initially
 112 //       * <code>null</code>.
 113 //       */
 114 //      private PackageDeclaration optionalPackageDeclaration = null;
 115 //
 116 //      /**
 117 //       * The list of import declarations in textual order order;
 118 //       * initially none (elementType: <code>ImportDeclaration</code>).
 119 //       */
 120 //      private ASTNode.NodeList imports =
 121 //              new ASTNode.NodeList(IMPORTS_PROPERTY);
 122 //
 123 //      /**
 124 //       * The list of type declarations in textual order order;
 125 //       * initially none (elementType: <code>AbstractTypeDeclaration</code>)
 126 //       */
 127 //      private ASTNode.NodeList types =
 128 //              new ASTNode.NodeList(TYPES_PROPERTY);
 129 //
 130 //      /**
 131 //       * Line end table. If <code>lineEndTable[i] == p</code> then the
 132 //       * line number <code>i+1</code> ends at character position
 133 //       * <code>p</code>. Except for the last line, the positions are that
 134 //       * of the last character of the line delimiter.
 135 //       * For example, the source string <code>A\nB\nC</code> has
 136 //       * line end table {1, 3} (if \n is one character).
 137 //       */
 138 //      private int[] lineEndTable = new int[0];
 139 //
 140 //      /**
 141 //       * Canonical empty list of messages.
 142 //       */
 143 //      private static final Message[] EMPTY_MESSAGES = new Message[0];
 144 //
 145 //      /**
 146 //       * Canonical empty list of problems.
 147 //       */
 148 //      private static final IProblem[] EMPTY_PROBLEMS = new IProblem[0];
 149 //
 150 //      /**
 151 //       * Messages reported by the compiler during parsing or name resolution.
 152 //       */
 153 //      private Message[] messages;
 154 //
 155 //      /**
 156 //       * Problems reported by the compiler during parsing or name resolution.
 157 //       */
 158 //      private IProblem[] problems = EMPTY_PROBLEMS;
 159 //
 160 //      /**
 161 //       * The comment mapper, or <code>null</code> in none;
 162 //       * initially <code>null</code>.
 163 //       * @since 3.0
 164 //       */
 165 //      private DefaultCommentMapper commentMapper = null;
 166 //
 167 //      /**
 168 //       * Sets the line end table for this compilation unit.
 169 //       * If <code>lineEndTable[i] == p</code> then line number <code>i+1</code>
 170 //       * ends at character position <code>p</code>. Except for the last line, the
 171 //       * positions are that of (the last character of) the line delimiter.
 172 //       * For example, the source string <code>A\nB\nC</code> has
 173 //       * line end table {1, 3, 4}.
 174 //       *
 175 //       * @param lineEndtable the line end table
 176 //       */
 177 //      void setLineEndTable(int[] lineEndTable) {
 178 //              if (lineEndTable == null) {
 179 //                      throw new NullPointerException();
 180 //              }
 181 //              // alternate root is *not* considered a structural property
 182 //              // but we protect them nevertheless
 183 //              checkModifiable();
 184 //              this.lineEndTable = lineEndTable;
 185 //      }
 186 //
 187 //      /**
 188 //       * Creates a new AST node for a compilation owned by the given AST.
 189 //       * The compilation unit initially has no package declaration, no
 190 //       * import declarations, and no type declarations.
 191 //       * <p>
 192 //       * N.B. This constructor is package-private; all subclasses must be
 193 //       * declared in the same package; clients are unable to declare
 194 //       * additional subclasses.
 195 //       * </p>
 196 //       *
 197 //       * @param ast the AST that is to own this node
 198 //       */
 199 //      CompilationUnit(AST ast) {
 200 //              super(ast);
 201 //      }
 202 //
 203 //      /* (omit javadoc for this method)
 204 //       * Method declared on ASTNode.
 205 //       * @since 3.0
 206 //       */
 207 //      final List internalStructuralPropertiesForType(int apiLevel) {
 208 //              return propertyDescriptors(apiLevel);
 209 //      }
 210 //
 211 //      /* (omit javadoc for this method)
 212 //       * Method declared on ASTNode.
 213 //       */
 214 //      final ASTNode internalGetSetChildProperty(ChildPropertyDescriptor property, boolean get, ASTNode child) {
 215 //              if (property == PACKAGE_PROPERTY) {
 216 //                      if (get) {
 217 //                              return getPackage();
 218 //                      } else {
 219 //                              setPackage((PackageDeclaration) child);
 220 //                              return null;
 221 //                      }
 222 //              }
 223 //              // allow default implementation to flag the error
 224 //              return super.internalGetSetChildProperty(property, get, child);
 225 //      }
 226 //
 227 //      /* (omit javadoc for this method)
 228 //       * Method declared on ASTNode.
 229 //       */
 230 //      final List internalGetChildListProperty(ChildListPropertyDescriptor property) {
 231 //              if (property == IMPORTS_PROPERTY) {
 232 //                      return imports();
 233 //              }
 234 //              if (property == TYPES_PROPERTY) {
 235 //                      return types();
 236 //              }
 237 //              // allow default implementation to flag the error
 238 //              return super.internalGetChildListProperty(property);
 239 //      }
 240 //
 241 //      /* (omit javadoc for this method)
 242 //       * Method declared on ASTNode.
 243 //       */
 244 //      final int getNodeType0() {
 245 //              return COMPILATION_UNIT;
 246 //      }
 247 //
 248 //      /* (omit javadoc for this method)
 249 //       * Method declared on ASTNode.
 250 //       */
 251 //      ASTNode clone0(AST target) {
 252 //              CompilationUnit result = new CompilationUnit(target);
 253 //              // n.b do not copy line number table or messages
 254 //              result.setSourceRange(this.getStartPosition(), this.getLength());
 255 //              result.setPackage(
 256 //                      (PackageDeclaration) ASTNode.copySubtree(target, getPackage()));
 257 //              result.imports().addAll(ASTNode.copySubtrees(target, imports()));
 258 //              result.types().addAll(ASTNode.copySubtrees(target, types()));
 259 //              return result;
 260 //      }
 261 //
 262 //      /* (omit javadoc for this method)
 263 //       * Method declared on ASTNode.
 264 //       */
 265 //      final boolean subtreeMatch0(ASTMatcher matcher, Object other) {
 266 //              // dispatch to correct overloaded match method
 267 //              return matcher.match(this, other);
 268 //      }
 269 //
 270 //      /* (omit javadoc for this method)
 271 //       * Method declared on ASTNode.
 272 //       */
 273 //      void accept0(ASTVisitor visitor) {
 274 //              boolean visitChildren = visitor.visit(this);
 275 //              if (visitChildren) {
 276 //                      // visit children in normal left to right reading order
 277 //                      acceptChild(visitor, getPackage());
 278 //                      acceptChildren(visitor, this.imports);
 279 //                      acceptChildren(visitor, this.types);
 280 //              }
 281 //              visitor.endVisit(this);
 282 //      }
 283 //
 284 //      /**
 285 //       * Returns the node for the package declaration of this compilation
 286 //       * unit, or <code>null</code> if this compilation unit is in the
 287 //       * default package.
 288 //       *
 289 //       * @return the package declaration node, or <code>null</code> if none
 290 //       */
 291 //      public PackageDeclaration getPackage() {
 292 //              return this.optionalPackageDeclaration;
 293 //      }
 294 //
 295 //      /**
 296 //       * Sets or clears the package declaration of this compilation unit
 297 //       * node to the given package declaration node.
 298 //       *
 299 //       * @param pkgDecl the new package declaration node, or
 300 //       *   <code>null</code> if this compilation unit does not have a package
 301 //       *   declaration (that is in the default package)
 302 //       * @exception IllegalArgumentException if:
 303 //       * <ul>
 304 //       * <li>the node belongs to a different AST</li>
 305 //       * <li>the node already has a parent</li>
 306 //       * </ul>
 307 //       */
 308 //      public void setPackage(PackageDeclaration pkgDecl) {
 309 //              ASTNode oldChild = this.optionalPackageDeclaration;
 310 //              preReplaceChild(oldChild, pkgDecl, PACKAGE_PROPERTY);
 311 //              this.optionalPackageDeclaration = pkgDecl;
 312 //              postReplaceChild(oldChild, pkgDecl, PACKAGE_PROPERTY);
 313 //      }
 314 //
 315 //      /**
 316 //       * Returns the live list of nodes for the import declarations of this
 317 //       * compilation unit, in order of appearance.
 318 //       *
 319 //       * @return the live list of import declaration nodes
 320 //       *    (elementType: <code>ImportDeclaration</code>)
 321 //       */
 322 //      public List imports() {
 323 //              return this.imports;
 324 //      }
 325 //
 326 //      /**
 327 //       * Returns the live list of nodes for the top-level type declarations of this
 328 //       * compilation unit, in order of appearance.
 329 //     * <p>
 330 //     * Note that in JLS3, the types may include both enum declarations
 331 //     * and annotation type declarations introduced in J2SE 1.5.
 332 //     * For JLS2, the elements are always <code>TypeDeclaration</code>.
 333 //     * </p>
 334 //       *
 335 //       * @return the live list of top-level type declaration
 336 //       *    nodes (elementType: <code>AbstractTypeDeclaration</code>)
 337 //       */
 338 //      public List types() {
 339 //              return this.types;
 340 //      }
 341 //
 342 //      /**
 343 //       * Finds the corresponding AST node in the given compilation unit from
 344 //       * which the given binding originated. Returns <code>null</code> if the
 345 //       * binding does not correspond to any node in this compilation unit.
 346 //       * This method always returns <code>null</code> if bindings were not requested
 347 //       * when this AST was built.
 348 //       * <p>
 349 //       * The following table indicates the expected node type for the various
 350 //       * different kinds of bindings:
 351 //       * <ul>
 352 //       * <li></li>
 353 //       * <li>package - a <code>PackageDeclaration</code></li>
 354 //       * <li>class or interface - a <code>TypeDeclaration</code> or a
 355 //       *    <code>AnonymousClassDeclaration</code> (for anonymous classes)</li>
 356 //       * <li>primitive type - none</li>
 357 //       * <li>array type - none</li>
 358 //       * <li>field - a <code>VariableDeclarationFragment</code> in a
 359 //       *    <code>FieldDeclaration</code> </li>
 360 //       * <li>local variable - a <code>SingleVariableDeclaration</code>, or
 361 //       *    a <code>VariableDeclarationFragment</code> in a
 362 //       *    <code>VariableDeclarationStatement</code> or
 363 //       *    <code>VariableDeclarationExpression</code></li>
 364 //       * <li>method - a <code>MethodDeclaration</code> </li>
 365 //       * <li>constructor - a <code>MethodDeclaration</code> </li>
 366 //     * <li>annotation type - an <code>AnnotationTypeDeclaration</code></li>
 367 //     * <li>annotation type member - an <code>AnnotationTypeMemberDeclaration</code></li>
 368 //     * <li>enum type - an <code>EnumDeclaration</code></li>
 369 //     * <li>enum constant - an <code>EnumConstantDeclaration</code></li>
 370 //       * </ul>
 371 //       * </p>
 372 //       * <p>
 373 //       * Each call to {@link ASTParser#createAST(IProgressMonitor)} with a request for bindings
 374 //       * gives rise to separate universe of binding objects. This method always returns
 375 //       * <code>null</code> when the binding object comes from a different AST.
 376 //       * Use <code>findDeclaringNode(binding.getKey())</code> when the binding comes
 377 //       * from a different AST.
 378 //       * </p>
 379 //       *
 380 //       * @param binding the binding
 381 //       * @return the corresponding node where the given binding is declared,
 382 //       * or <code>null</code> if the binding does not correspond to a node in this
 383 //       * compilation unit or if bindings were not requested when this AST was built
 384 //       * @see #findDeclaringNode(String)
 385 //       */
 386 //      public ASTNode findDeclaringNode(IBinding binding) {
 387 //              return this.ast.getBindingResolver().findDeclaringNode(binding);
 388 //      }
 389 //
 390 //      /**
 391 //       * Finds the corresponding AST node in the given compilation unit from
 392 //       * which the binding with the given key originated. Returns
 393 //       * <code>null</code> if the corresponding node cannot be determined.
 394 //       * This method always returns <code>null</code> if bindings were not requested
 395 //       * when this AST was built.
 396 //       * <p>
 397 //       * The following table indicates the expected node type for the various
 398 //       * different kinds of binding keys:
 399 //       * <ul>
 400 //       * <li></li>
 401 //       * <li>package - a <code>PackageDeclaration</code></li>
 402 //       * <li>class or interface - a <code>TypeDeclaration</code> or a
 403 //       *    <code>AnonymousClassDeclaration</code> (for anonymous classes)</li>
 404 //       * <li>primitive type - none</li>
 405 //       * <li>array type - none</li>
 406 //       * <li>field - a <code>VariableDeclarationFragment</code> in a
 407 //       *    <code>FieldDeclaration</code> </li>
 408 //       * <li>local variable - a <code>SingleVariableDeclaration</code>, or
 409 //       *    a <code>VariableDeclarationFragment</code> in a
 410 //       *    <code>VariableDeclarationStatement</code> or
 411 //       *    <code>VariableDeclarationExpression</code></li>
 412 //       * <li>method - a <code>MethodDeclaration</code> </li>
 413 //       * <li>constructor - a <code>MethodDeclaration</code> </li>
 414 //     * <li>annotation type - an <code>AnnotationTypeDeclaration</code></li>
 415 //     * <li>annotation type member - an <code>AnnotationTypeMemberDeclaration</code></li>
 416 //     * <li>enum type - an <code>EnumDeclaration</code></li>
 417 //     * <li>enum constant - an <code>EnumConstantDeclaration</code></li>
 418 //       * </ul>
 419 //       * </p>
 420 //       * <p>
 421 //       * Note that as explained in {@link IBinding#getKey() IBinding.getkey}
 422 //       * there may be no keys for finding the declaring node for local variables,
 423 //       * local or anonymous classes, etc.
 424 //       * </p>
 425 //       *
 426 //       * @param key the binding key, or <code>null</code>
 427 //       * @return the corresponding node where a binding with the given
 428 //       * key is declared, or <code>null</code> if the key is <code>null</code>
 429 //       * or if the key does not correspond to a node in this compilation unit
 430 //       * or if bindings were not requested when this AST was built
 431 //       * @see IBinding#getKey()
 432 //       * @since 2.1
 433 //       */
 434 //      public ASTNode findDeclaringNode(String key) {
 435 //              return this.ast.getBindingResolver().findDeclaringNode(key);
 436 //      }
 437 //
 438 //      /**
 439 //       * Returns the internal comment mapper.
 440 //       *
 441 //       * @return the comment mapper, or <code>null</code> if none.
 442 //       * @since 3.0
 443 //       */
 444 //      DefaultCommentMapper getCommentMapper() {
 445 //              return this.commentMapper;
 446 //      }
 447 //
 448 //      /**
 449 //       * Initializes the internal comment mapper with the given
 450 //       * scanner.
 451 //       *
 452 //       * @param scanner the scanner
 453 //       * @since 3.0
 454 //       */
 455 //      void initCommentMapper(Scanner scanner) {
 456 //              this.commentMapper = new DefaultCommentMapper(this.optionalCommentTable);
 457 //              this.commentMapper.initialize(this, scanner);
 458 //      }
 459 //
 460 //      /**
 461 //       * Returns the extended start position of the given node. Unlike
 462 //       * {@link ASTNode#getStartPosition()} and {@link ASTNode#getLength()()},
 463 //       * the extended source range may include comments and whitespace
 464 //       * immediately before or after the normal source range for the node.
 465 //       *
 466 //       * @param node the node
 467 //       * @return the 0-based character index, or <code>-1</code>
 468 //       *    if no source position information is recorded for this node
 469 //       * @see #getExtendedLength(ASTNode)
 470 //       * @since 3.0
 471 //       */
 472 //      public int getExtendedStartPosition(ASTNode node) {
 473 //              if (this.commentMapper == null) {
 474 //                      return -1;
 475 //              } else {
 476 //                      return this.commentMapper.getExtendedStartPosition(node);
 477 //              }
 478 //      }
 479 //
 480 //      /**
 481 //       * Returns the extended source length of the given node. Unlike
 482 //       * {@link ASTNode#getStartPosition()} and {@link ASTNode#getLength()()},
 483 //       * the extended source range may include comments and whitespace
 484 //       * immediately before or after the normal source range for the node.
 485 //       *
 486 //       * @param node the node
 487 //       * @return a (possibly 0) length, or <code>0</code>
 488 //       *    if no source position information is recorded for this node
 489 //       * @see #getExtendedStartPosition(ASTNode)
 490 //       * @since 3.0
 491 //       */
 492 //      public int getExtendedLength(ASTNode node) {
 493 //              if (this.commentMapper == null) {
 494 //                      return 0;
 495 //              } else {
 496 //                      return this.commentMapper.getExtendedLength(node);
 497 //              }
 498 //      }
 499 //
 500 //      /**
 501 //       * Returns the line number corresponding to the given source character
 502 //       * position in the original source string. The initial line of the
 503 //       * compilation unit is numbered 1, and each line extends through the
 504 //       * last character of the end-of-line delimiter. The very last line extends
 505 //       * through the end of the source string and has no line delimiter.
 506 //       * For example, the source string <code>class A\n{\n}</code> has 3 lines
 507 //       * corresponding to inclusive character ranges [0,7], [8,9], and [10,10].
 508 //       * Returns 1 for a character position that does not correspond to any
 509 //       * source line, or if no line number information is available for this
 510 //       * compilation unit.
 511 //       *
 512 //       * @param position a 0-based character position, possibly
 513 //       *   negative or out of range
 514 //       * @return the 1-based line number, or <code>1</code> if the character
 515 //       *    position does not correspond to a source line in the original
 516 //       *    source file or if line number information is not known for this
 517 //       *    compilation unit
 518 //       * @see ASTParser
 519 //       */
 520 //      public int lineNumber(int position) {
 521 //              int length = lineEndTable.length;
 522 //              if (length == 0) {
 523 //                      // no line number info
 524 //                      return 1;
 525 //              }
 526 //              int low = 0;
 527 //              if (position <= lineEndTable[low]) {
 528 //                      // position illegal or before the first line delimiter
 529 //                      return 1;
 530 //              }
 531 //              // assert position > lineEndTable[low+1]  && low == 0
 532 //              int hi = length - 1;
 533 //              if (position > lineEndTable[hi]) {
 534 //                      // position beyond the last line separator
 535 //                      if (position >= getStartPosition() + getLength()) {
 536 //                              // this is beyond the end of the source length
 537 //                              return 1;
 538 //                      } else {
 539 //                              return length + 1;
 540 //                      }
 541 //              }
 542 //              // assert lineEndTable[low]  < position <= lineEndTable[hi]
 543 //              // && low == 0 && hi == length - 1 && low < hi
 544 //
 545 //              // binary search line end table
 546 //              while (true) {
 547 //                      // invariant lineEndTable[low] < position <= lineEndTable[hi]
 548 //                      // && 0 <= low < hi <= length - 1
 549 //                      // reducing measure hi - low
 550 //                      if (low + 1 == hi) {
 551 //                              // assert lineEndTable[low] < position <= lineEndTable[low+1]
 552 //                              // position is on line low+1 (line number is low+2)
 553 //                              return low + 2;
 554 //                      }
 555 //                      // assert hi - low >= 2, so average is truly in between
 556 //                      int mid = (low + hi) / 2;
 557 //                      // assert 0 <= low < mid < hi <= length - 1
 558 //                      if (position <= lineEndTable[mid]) {
 559 //                              // assert lineEndTable[low] < position <= lineEndTable[mid]
 560 //                              // && 0 <= low < mid < hi <= length - 1
 561 //                              hi = mid;
 562 //                      } else {
 563 //                              // position > lineEndTable[mid]
 564 //                              // assert lineEndTable[mid] < position <= lineEndTable[hi]
 565 //                              // && 0 <= low < mid < hi <= length - 1
 566 //                              low = mid;
 567 //                      }
 568 //                      // in both cases, invariant reachieved with reduced measure
 569 //              }
 570 //      }
 571 //
 572 //      /**
 573 //       * Returns the list of messages reported by the compiler during the parsing
 574 //       * or the type checking of this compilation unit. This list might be a subset of
 575 //       * errors detected and reported by a Java compiler.
 576 //       * <p>
 577 //       * This list of messages is suitable for simple clients that do little
 578 //       * more than log the messages or display them to the user. Clients that
 579 //       * need further details should call <code>getProblems</code> to get
 580 //       * compiler problem objects.
 581 //       * </p>
 582 //       *
 583 //       * @return the list of messages, possibly empty
 584 //       * @see #getProblems()
 585 //       * @see ASTParser
 586 //       */
 587 //      public Message[] getMessages() {
 588 //              if (this.messages == null) {
 589 //                      int problemLength = this.problems.length;
 590 //                      if (problemLength == 0) {
 591 //                              this.messages = EMPTY_MESSAGES;
 592 //                      } else {
 593 //                              this.messages = new Message[problemLength];
 594 //                              for (int i = 0; i < problemLength; i++) {
 595 //                                      IProblem problem = this.problems[i];
 596 //                                      int start = problem.getSourceStart();
 597 //                                      int end = problem.getSourceEnd();
 598 //                                      messages[i] = new Message(problem.getMessage(), start, end - start + 1);
 599 //                              }
 600 //                      }
 601 //              }
 602 //              return this.messages;
 603 //      }
 604 //
 605 //      /**
 606 //       * Returns the list of detailed problem reports noted by the compiler
 607 //       * during the parsing or the type checking of this compilation unit. This
 608 //       * list might be a subset of errors detected and reported by a Java
 609 //       * compiler.
 610 //       * <p>
 611 //       * Simple clients that do little more than log the messages or display
 612 //       * them to the user should probably call <code>getMessages</code> instead.
 613 //       * </p>
 614 //       *
 615 //       * @return the list of detailed problem objects, possibly empty
 616 //       * @see #getMessages()
 617 //       * @see ASTParser
 618 //       * @since 2.1
 619 //       */
 620 //      public IProblem[] getProblems() {
 621 //              return this.problems;
 622 //      }
 623 //
 624 //      /**
 625 //       * Sets the array of problems reported by the compiler during the parsing or
 626 //       * name resolution of this compilation unit.
 627 //       *
 628 //       * @param problems the list of problems
 629 //       */
 630 //      void setProblems(IProblem[] problems) {
 631 //              if (problems == null) {
 632 //                      throw new IllegalArgumentException();
 633 //              }
 634 //              this.problems = problems;
 635 //      }
 636 //
 637 //      /**
 638 //       * Returns a list of the comments encountered while parsing
 639 //       * this compilation unit.
 640 //       * <p>
 641 //       * Since the Java language allows comments to appear most anywhere
 642 //       * in the source text, it is problematic to locate comments in relation
 643 //       * to the structure of an AST. The one exception is doc comments
 644 //       * which, by convention, immediately precede type, field, and
 645 //       * method declarations; these comments are located in the AST
 646 //       * by {@link  BodyDeclaration#getJavadoc BodyDeclaration.getJavadoc}.
 647 //       * Other comments do not show up in the AST. The table of comments
 648 //       * is provided for clients that need to find the source ranges of
 649 //       * all comments in the original source string. It includes entries
 650 //       * for comments of all kinds (line, block, and doc), arranged in order
 651 //       * of increasing source position.
 652 //       * </p>
 653 //       * Note on comment parenting: The {@link ASTNode#getParent() getParent()}
 654 //       * of a doc comment associated with a body declaration is the body
 655 //       * declaration node; for these comment nodes
 656 //       * {@link ASTNode#getRoot() getRoot()} will return the compilation unit
 657 //       * (assuming an unmodified AST) reflecting the fact that these nodes
 658 //       * are property located in the AST for the compilation unit.
 659 //       * However, for other comment nodes, {@link ASTNode#getParent() getParent()}
 660 //       * will return <code>null</code>, and {@link ASTNode#getRoot() getRoot()}
 661 //       * will return the comment node itself, indicating that these comment nodes
 662 //       * are not directly connected to the AST for the compilation unit. The
 663 //       * {@link Comment#getAlternateRoot Comment.getAlternateRoot}
 664 //       * method provides a way to navigate from a comment to its compilation
 665 //       * unit.
 666 //       * </p>
 667 //       * <p>
 668 //       * A note on visitors: The only comment nodes that will be visited when
 669 //       * visiting a compilation unit are the doc comments parented by body
 670 //       * declarations. To visit all comments in normal reading order, iterate
 671 //       * over the comment table and call {@link ASTNode#accept(ASTVisitor) accept}
 672 //       * on each element.
 673 //       * </p>
 674 //       * <p>
 675 //       * Clients cannot modify the resulting list.
 676 //       * </p>
 677 //       *
 678 //       * @return an unmodifiable list of comments in increasing order of source
 679 //       * start position, or <code>null</code> if comment information
 680 //       * for this compilation unit is not available
 681 //       * @see ASTParser
 682 //       * @since 3.0
 683 //       */
 684 //      public List getCommentList() {
 685 //              return this.optionalCommentList;
 686 //      }
 687 //
 688 //      /**
 689 //       * Sets the list of the comments encountered while parsing
 690 //       * this compilation unit.
 691 //       *
 692 //       * @param commentTable a list of comments in increasing order
 693 //       * of source start position, or <code>null</code> if comment
 694 //       * information for this compilation unit is not available
 695 //       * @exception IllegalArgumentException if the comment table is
 696 //       * not in increasing order of source position
 697 //       * @see #getCommentList()
 698 //       * @see ASTParser
 699 //       * @since 3.0
 700 //       */
 701 //      void setCommentTable(Comment[] commentTable) {
 702 //              // double check table to ensure that all comments have
 703 //              // source positions and are in strictly increasing order
 704 //              if (commentTable == null) {
 705 //                      this.optionalCommentList = null;
 706 //                      this.optionalCommentTable = null;
 707 //              } else {
 708 //                      int nextAvailablePosition = 0;
 709 //                      for (int i = 0; i < commentTable.length; i++) {
 710 //                              Comment comment = commentTable[i];
 711 //                              if (comment == null) {
 712 //                                      throw new IllegalArgumentException();
 713 //                              }
 714 //                              int start = comment.getStartPosition();
 715 //                              int length = comment.getLength();
 716 //                              if (start < 0 || length < 0 || start < nextAvailablePosition) {
 717 //                                      throw new IllegalArgumentException();
 718 //                              }
 719 //                              nextAvailablePosition = comment.getStartPosition() + comment.getLength();
 720 //                      }
 721 //                      this.optionalCommentTable = commentTable;
 722 //                      List commentList = Arrays.asList(commentTable);
 723 //                      // protect the list from further modification
 724 //                      this.optionalCommentList = Collections.unmodifiableList(commentList);
 725 //              }
 726 //      }
 727 //
 728 //
 729 //      /* (omit javadoc for this method)
 730 //       * Method declared on ASTNode.
 731 //       */
 732 //      void appendDebugString(StringBuffer buffer) {
 733 //              buffer.append("CompilationUnit"); //$NON-NLS-1$
 734 //              // include the type names
 735 //              buffer.append("["); //$NON-NLS-1$
 736 //              for (Iterator it = types().iterator(); it.hasNext(); ) {
 737 //                      AbstractTypeDeclaration d = (AbstractTypeDeclaration) it.next();
 738 //                      buffer.append(d.getName().getIdentifier());
 739 //                      if (it.hasNext()) {
 740 //                              buffer.append(","); //$NON-NLS-1$
 741 //                      }
 742 //              }
 743 //              buffer.append("]"); //$NON-NLS-1$
 744 //      }
 745 //
 746 //      /* (omit javadoc for this method)
 747 //       * Method declared on ASTNode.
 748 //       */
 749 //      int memSize() {
 750 //              int size = BASE_NODE_SIZE + 8 * 4;
 751 //              if (this.lineEndTable != null) {
 752 //                      size += HEADERS + 4 * this.lineEndTable.length;
 753 //              }
 754 //              if (this.optionalCommentTable != null) {
 755 //                      size += HEADERS + 4 * this.optionalCommentTable.length;
 756 //              }
 757 //              // ignore the space taken up by optionalCommentList
 758 //              return size;
 759 //      }
 760 //
 761 //      /* (omit javadoc for this method)
 762 //       * Method declared on ASTNode.
 763 //       */
 764 //      int treeSize() {
 765 //              int size = memSize();
 766 //              if (this.optionalPackageDeclaration != null) {
 767 //                      size += getPackage().treeSize();
 768 //              }
 769 //              size += this.imports.listSize();
 770 //              size += this.types.listSize();
 771 //              // include disconnected comments
 772 //              if (this.optionalCommentList != null) {
 773 //                      for (int i = 0; i < this.optionalCommentList.size(); i++) {
 774 //                              Comment comment = (Comment) this.optionalCommentList.get(i);
 775 //                              if (comment != null && comment.getParent() == null) {
 776 //                                      size += comment.treeSize();
 777 //                              }
 778 //                      }
 779 //              }
 780 //              return size;
 781 //      }
 782 //
 783 //      /**
 784 //       * Enables the recording of changes to this compilation
 785 //       * unit and its descendents. The compilation unit must have
 786 //       * been created by <code>ASTParser</code> and still be in
 787 //       * its original state. Once recording is on,
 788 //       * arbitrary changes to the subtree rooted at this compilation
 789 //       * unit are recorded internally. Once the modification has
 790 //       * been completed, call <code>rewrite</code> to get an object
 791 //       * representing the corresponding edits to the original
 792 //       * source code string.
 793 //       *
 794 //       * @exception IllegalArgumentException if this compilation unit is
 795 //       * marked as unmodifiable, or if this compilation unit has already
 796 //       * been tampered with, or recording has already been enabled
 797 //       * @since 3.0
 798 //       */
 799 //      public void recordModifications() {
 800 //              getAST().recordModifications(this);
 801 //      }
 802 //
 803 //      /**
 804 //       * Converts all modifications recorded for this compilation
 805 //       * unit into an object representing the corresponding text
 806 //       * edits to the given document containing the original source
 807 //       * code for this compilation unit.
 808 //       * <p>
 809 //       * The compilation unit must have been created by
 810 //       * <code>ASTParser</code> from the source code string in the
 811 //       * given document, and recording must have been turned
 812 //       * on with a prior call to <code>recordModifications</code>
 813 //       * while the AST was still in its original state.
 814 //       * </p>
 815 //       * <p>
 816 //       * Calling this methods does not discard the modifications
 817 //       * on record. Subsequence modifications made to the AST
 818 //       * are added to the ones already on record. If this method
 819 //       * is called again later, the resulting text edit object will
 820 //       * accurately reflect the net cumulative affect of all those
 821 //       * changes.
 822 //       * </p>
 823 //       *
 824 //       * @param document original document containing source code
 825 //       * for this compilation unit
 826 //       * @param options the table of formatter options
 827 //       * (key type: <code>String</code>; value type: <code>String</code>);
 828 //       * or <code>null</code> to use the standard global options
 829 //       * {@link JavaCore#getOptions() JavaCore.getOptions()}.
 830 //       * @return text edit object describing the changes to the
 831 //       * document corresponding to the recorded AST modifications
 832 //       * @exception IllegalArgumentException if the document passed is
 833 //       * <code>null</code> or does not correspond to this AST
 834 //       * @exception IllegalStateException if <code>recordModifications</code>
 835 //       * was not called to enable recording
 836 //       * @see #recordModifications()
 837 //       * @since 3.0
 838 //       */
 839 //      public TextEdit rewrite(IDocument document, Map options) {
 840 //              return getAST().rewrite(document, options);
 841 //      }
 842 }
 843