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

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