< prev index next >

src/java.desktop/share/classes/javax/swing/text/ElementIterator.java

Print this page

        

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -23,62 +23,69 @@
  * questions.
  */
 
 package javax.swing.text;
 
-import java.util.Enumeration;
 import java.util.Stack;
+import java.util.Enumeration;
 
 /**
- * {@code ElementIterator}, as the name suggests, iterates over the
- * {@code Element} tree. The constructor can be invoked with either
- * {@code Document} or an {@code Element} as an argument. If the constructor is
- * invoked with a {@code Document} as an argument then the root of the iteration
- * is the return value of {@code document.getDefaultRootElement()}.
- * <p>
- * The iteration happens in a depth-first manner. In terms of how boundary
- * conditions are handled:
- * <ul>
- *   <li>if {@link #next} is called before {@link #first} or {@link #current},
- *   the root will be returned
- *   <li>{@link #next} returns {@code null} to indicate the end of the list
- *   <li>{@link #previous} returns {@code null} when the current element is the
- *   root or {@link #next} has returned {@code null}
- * </ul>
  * <p>
- * The {@code ElementIterator} does no locking of the {@code Element} tree. This
- * means that it does not track any changes. It is the responsibility of the
+ * ElementIterator, as the name suggests, iterates over the Element
+ * tree.  The constructor can be invoked with either Document or an Element
+ * as an argument.  If the constructor is invoked with a Document as an
+ * argument then the root of the iteration is the return value of
+ * document.getDefaultRootElement().
+ *
+ * The iteration happens in a depth-first manner.  In terms of how
+ * boundary conditions are handled:
+ * a) if next() is called before first() or current(), the
+ *    root will be returned.
+ * b) next() returns null to indicate the end of the list.
+ * c) previous() returns null when the current element is the root
+ *    or next() has returned null.
+ *
+ * The ElementIterator does no locking of the Element tree. This means
+ * that it does not track any changes.  It is the responsibility of the
  * user of this class, to ensure that no changes happen during element
  * iteration.
- * <p>
+ *
  * Simple usage example:
- * <pre>{@code public void iterate() {
- *      ElementIterator it = new ElementIterator(root);
- *      Element elem;
- *      while (true) {
- *          if ((elem = it.next()) != null) {
- *              // process element
- *              System.out.println("elem: " + elem.getName());
- *          } else {
- *              break;
- *          }
- *      }
- * }}</pre>
+ *
+ *    public void iterate() {
+ *        ElementIterator it = new ElementIterator(root);
+ *        Element elem;
+ *        while (true) {
+ *           if ((elem = next()) != null) {
+ *               // process element
+ *               System.out.println("elem: " + elem.getName());
+ *           } else {
+ *               break;
+ *           }
+ *        }
+ *    }
  *
  * @author Sunita Mani
+ *
  */
+
 public class ElementIterator implements Cloneable {
 
+
     private Element root;
     private Stack<StackItem> elementStack = null;
 
     /**
-     * The {@code StackItem} class stores the element as well as a child index.
-     * If the index is -1, then the element represented on the stack is the
-     * element itself. Otherwise, the index functions as an index into the
-     * vector of children of the element. In this case, the item on the stack
-     * represents the "index"th child of the element.
+     * The StackItem class stores the element
+     * as well as a child index.  If the
+     * index is -1, then the element represented
+     * on the stack is the element itself.
+     * Otherwise, the index functions as an index
+     * into the vector of children of the element.
+     * In this case, the item on the stack
+     * represents the "index"th child of the element
+     *
      */
     private class StackItem implements Cloneable {
         Element item;
         int childIndex;
 

@@ -108,32 +115,35 @@
             return super.clone();
         }
     }
 
     /**
-     * Creates a new {@code ElementIterator}. The root element is taken to get
-     * the default root element of the document.
+     * Creates a new ElementIterator. The
+     * root element is taken to get the
+     * default root element of the document.
      *
-     * @param  document a {@code Document}
+     * @param document a Document.
      */
     public ElementIterator(Document document) {
         root = document.getDefaultRootElement();
     }
 
+
     /**
-     * Creates a new {@code ElementIterator}.
+     * Creates a new ElementIterator.
      *
-     * @param  root the root {@code Element}
+     * @param root the root Element.
      */
     public ElementIterator(Element root) {
         this.root = root;
     }
 
+
     /**
-     * Clones the {@code ElementIterator}.
+     * Clones the ElementIterator.
      *
-     * @return a cloned {@code ElementIterator} Object
+     * @return a cloned ElementIterator Object.
      */
     public synchronized Object clone() {
 
         try {
             ElementIterator it = new ElementIterator(root);

@@ -149,14 +159,15 @@
         } catch (CloneNotSupportedException e) {
             throw new InternalError(e);
         }
     }
 
+
     /**
      * Fetches the first element.
      *
-     * @return an {@code Element}
+     * @return an Element.
      */
     public Element first() {
         // just in case...
         if (root == null) {
             return null;

@@ -170,24 +181,25 @@
     }
 
     /**
      * Fetches the current depth of element tree.
      *
-     * @return the depth
+     * @return the depth.
      */
     public int depth() {
         if (elementStack == null) {
             return 0;
         }
         return elementStack.size();
     }
 
+
     /**
-     * Fetches the current {@code Element}.
+     * Fetches the current Element.
      *
-     * @return element on top of the stack or {@code null} if the root element
-     *         is {@code null}
+     * @return element on top of the stack or
+     *          <code>null</code> if the root element is <code>null</code>
      */
     public Element current() {
 
         if (elementStack == null) {
             return first();

@@ -208,15 +220,18 @@
             return elem.getElement(index);
         }
         return null;
     }
 
+
     /**
-     * Fetches the next {@code Element}. The strategy used to locate the next
-     * element is a depth-first search.
+     * Fetches the next Element. The strategy
+     * used to locate the next element is
+     * a depth-first search.
      *
-     * @return the next element or {@code null} at the end of the list
+     * @return the next element or <code>null</code>
+     *          at the end of the list.
      */
     public Element next() {
 
         /* if current() has not been invoked
            and next is invoked, the very first

@@ -265,16 +280,18 @@
             }
         }
         return null;
     }
 
+
     /**
-     * Fetches the previous {@code Element}. If however the current element is
-     * the last element, or the current element is {@code null}, then
-     * {@code null} is returned.
+     * Fetches the previous Element. If however the current
+     * element is the last element, or the current element
+     * is null, then null is returned.
+     *
+     * @return previous <code>Element</code> if available
      *
-     * @return previous {@code Element} if available
      */
     public Element previous() {
 
         int stackSize;
         if (elementStack == null || (stackSize = elementStack.size()) == 0) {

@@ -316,12 +333,12 @@
         // should never get here.
         return null;
     }
 
     /**
-     * Returns the last child of {@code parent} that is a leaf. If the last
-     * child is a not a leaf, this method is called with the last child.
+     * Returns the last child of <code>parent</code> that is a leaf. If the
+     * last child is a not a leaf, this method is called with the last child.
      */
     private Element getDeepestLeaf(Element parent) {
         if (parent.isLeaf()) {
             return parent;
         }

@@ -330,14 +347,14 @@
             return parent;
         }
         return getDeepestLeaf(parent.getElement(childCount - 1));
     }
 
-    /**
-     * Iterates through the element tree and prints out each element and its
-     * attributes.
-     */
+    /*
+      Iterates through the element tree and prints
+      out each element and its attributes.
+    */
     private void dumpTree() {
 
         Element elem;
         while (true) {
             if ((elem = next()) != null) {
< prev index next >