< prev index next >

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

Print this page

        

@@ -45,11 +45,11 @@
  * <p>
  * This class implements a locking mechanism for the document.  It
  * allows multiple readers or one writer, and writers must wait until
  * all observers of the document have been notified of a previous
  * change before beginning another mutation to the document.  The
- * read lock is acquired and released using the <code>render</code>
+ * read lock is acquired and released using the {@code render}
  * method.  A write lock is acquired by the methods that mutate the
  * document, and are held for the duration of the method call.
  * Notification is done on the thread that produced the mutation,
  * and the thread has full read access to the document for the
  * duration of the notification, but other readers are kept out

@@ -60,59 +60,58 @@
  * Any models subclassed from this class and used in conjunction
  * with a text component that has a look and feel implementation
  * that is derived from BasicTextUI may be safely updated
  * asynchronously, because all access to the View hierarchy
  * is serialized by BasicTextUI if the document is of type
- * <code>AbstractDocument</code>.  The locking assumes that an
+ * {@code AbstractDocument}.  The locking assumes that an
  * independent thread will access the View hierarchy only from
  * the DocumentListener methods, and that there will be only
  * one event thread active at a time.
  * <p>
  * If concurrency support is desired, there are the following
  * additional implications.  The code path for any DocumentListener
  * implementation and any UndoListener implementation must be threadsafe,
  * and not access the component lock if trying to be safe from deadlocks.
- * The <code>repaint</code> and <code>revalidate</code> methods
+ * The {@code repaint} and {@code revalidate} methods
  * on JComponent are safe.
  * <p>
  * AbstractDocument models an implied break at the end of the document.
  * Among other things this allows you to position the caret after the last
- * character. As a result of this, <code>getLength</code> returns one less
+ * character. As a result of this, {@code getLength} returns one less
  * than the length of the Content. If you create your own Content, be
  * sure and initialize it to have an additional character. Refer to
  * StringContent and GapContent for examples of this. Another implication
  * of this is that Elements that model the implied end character will have
  * an endOffset == (getLength() + 1). For example, in DefaultStyledDocument
- * <code>getParagraphElement(getLength()).getEndOffset() == getLength() + 1
- * </code>.
+ * {@code getParagraphElement(getLength()).getEndOffset() == getLength() + 1}.
  * <p>
  * <strong>Warning:</strong>
  * Serialized objects of this class will not be compatible with
  * future Swing releases. The current serialization support is
  * appropriate for short term storage or RMI between applications running
  * the same version of Swing.  As of 1.4, support for long term storage
  * of all JavaBeans&trade;
- * has been added to the <code>java.beans</code> package.
+ * has been added to the {@code java.beans} package.
  * Please see {@link java.beans.XMLEncoder}.
  *
  * @author  Timothy Prinzing
  */
 @SuppressWarnings("serial") // Same-version serialization only
 public abstract class AbstractDocument implements Document, Serializable {
 
     /**
-     * Constructs a new <code>AbstractDocument</code>, wrapped around some
+     * Constructs a new {@code AbstractDocument}, wrapped around some
      * specified content storage mechanism.
      *
      * @param data the content
      */
     protected AbstractDocument(Content data) {
         this(data, StyleContext.getDefaultStyleContext());
     }
 
     /**
-     * Constructs a new <code>AbstractDocument</code>, wrapped around some
+     * Constructs a new {@code AbstractDocument}, wrapped around some
      * specified content storage mechanism.
      *
      * @param data the content
      * @param context the attribute context
      */

@@ -153,14 +152,14 @@
         }
     }
 
     /**
      * Supports managing a set of properties. Callers
-     * can use the <code>documentProperties</code> dictionary
+     * can use the {@code documentProperties} dictionary
      * to annotate the document with document-wide properties.
      *
-     * @return a non-<code>null</code> <code>Dictionary</code>
+     * @return a non-{@code null Dictionary}
      * @see #setDocumentProperties
      */
     public Dictionary<Object,Object> getDocumentProperties() {
         if (documentProperties == null) {
             documentProperties = new Hashtable<Object, Object>(2);

@@ -295,15 +294,15 @@
      * upon this document.
      * <code><em>Foo</em>Listener</code>s are registered using the
      * <code>add<em>Foo</em>Listener</code> method.
      *
      * <p>
-     * You can specify the <code>listenerType</code> argument
+     * You can specify the {@code listenerType} argument
      * with a class literal, such as
      * <code><em>Foo</em>Listener.class</code>.
      * For example, you can query a
-     * document <code>d</code>
+     * document {@code d}
      * for its document listeners with the following code:
      *
      * <pre>DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));</pre>
      *
      * If no such listeners exist, this method returns an empty array.

@@ -312,13 +311,13 @@
      * @param listenerType the type of listeners requested
      * @return an array of all objects registered as
      *          <code><em>Foo</em>Listener</code>s on this component,
      *          or an empty array if no such
      *          listeners have been added
-     * @exception ClassCastException if <code>listenerType</code>
+     * @exception ClassCastException if {@code listenerType}
      *          doesn't specify a class or interface that implements
-     *          <code>java.util.EventListener</code>
+     *          {@code java.util.EventListener}
      *
      * @see #getDocumentListeners
      * @see #getUndoableEditListeners
      *
      * @since 1.3

@@ -329,11 +328,11 @@
 
     /**
      * Gets the asynchronous loading priority.  If less than zero,
      * the document should not be loaded asynchronously.
      *
-     * @return the asynchronous loading priority, or <code>-1</code>
+     * @return the asynchronous loading priority, or {@code -1}
      *   if the document should not be loaded asynchronously
      */
     public int getAsynchronousLoadPriority() {
         Integer loadPriority = (Integer)
             getProperty(AbstractDocument.AsyncLoadPriority);

@@ -353,26 +352,26 @@
         Integer loadPriority = (p >= 0) ? Integer.valueOf(p) : null;
         putProperty(AbstractDocument.AsyncLoadPriority, loadPriority);
     }
 
     /**
-     * Sets the <code>DocumentFilter</code>. The <code>DocumentFilter</code>
-     * is passed <code>insert</code> and <code>remove</code> to conditionally
-     * allow inserting/deleting of the text.  A <code>null</code> value
+     * Sets the {@code DocumentFilter}. The {@code DocumentFilter}
+     * is passed {@code insert} and {@code remove} to conditionally
+     * allow inserting/deleting of the text.  A {@code null} value
      * indicates that no filtering will occur.
      *
-     * @param filter the <code>DocumentFilter</code> used to constrain text
+     * @param filter the {@code DocumentFilter} used to constrain text
      * @see #getDocumentFilter
      * @since 1.4
      */
     public void setDocumentFilter(DocumentFilter filter) {
         documentFilter = filter;
     }
 
     /**
-     * Returns the <code>DocumentFilter</code> that is responsible for
-     * filtering of insertion/removal. A <code>null</code> return value
+     * Returns the {@code DocumentFilter} that is responsible for
+     * filtering of insertion/removal. A {@code null} return value
      * implies no filtering is to occur.
      *
      * @since 1.4
      * @see #setDocumentFilter
      * @return the DocumentFilter

@@ -434,32 +433,32 @@
     }
 
     /**
      * Adds a document listener for notification of any changes.
      *
-     * @param listener the <code>DocumentListener</code> to add
+     * @param listener the {@code DocumentListener} to add
      * @see Document#addDocumentListener
      */
     public void addDocumentListener(DocumentListener listener) {
         listenerList.add(DocumentListener.class, listener);
     }
 
     /**
      * Removes a document listener.
      *
-     * @param listener the <code>DocumentListener</code> to remove
+     * @param listener the {@code DocumentListener} to remove
      * @see Document#removeDocumentListener
      */
     public void removeDocumentListener(DocumentListener listener) {
         listenerList.remove(DocumentListener.class, listener);
     }
 
     /**
      * Returns an array of all the document listeners
      * registered on this document.
      *
-     * @return all of this document's <code>DocumentListener</code>s
+     * @return all of this document's {@code DocumentListener}s
      *         or an empty array if no document listeners are
      *         currently registered
      *
      * @see #addDocumentListener
      * @see #removeDocumentListener

@@ -469,36 +468,36 @@
         return listenerList.getListeners(DocumentListener.class);
     }
 
     /**
      * Adds an undo listener for notification of any changes.
-     * Undo/Redo operations performed on the <code>UndoableEdit</code>
+     * Undo/Redo operations performed on the {@code UndoableEdit}
      * will cause the appropriate DocumentEvent to be fired to keep
      * the view(s) in sync with the model.
      *
-     * @param listener the <code>UndoableEditListener</code> to add
+     * @param listener the {@code UndoableEditListener} to add
      * @see Document#addUndoableEditListener
      */
     public void addUndoableEditListener(UndoableEditListener listener) {
         listenerList.add(UndoableEditListener.class, listener);
     }
 
     /**
      * Removes an undo listener.
      *
-     * @param listener the <code>UndoableEditListener</code> to remove
+     * @param listener the {@code UndoableEditListener} to remove
      * @see Document#removeDocumentListener
      */
     public void removeUndoableEditListener(UndoableEditListener listener) {
         listenerList.remove(UndoableEditListener.class, listener);
     }
 
     /**
      * Returns an array of all the undoable edit listeners
      * registered on this document.
      *
-     * @return all of this document's <code>UndoableEditListener</code>s
+     * @return all of this document's {@code UndoableEditListener}s
      *         or an empty array if no undoable edit listeners are
      *         currently registered
      *
      * @see #addUndoableEditListener
      * @see #removeUndoableEditListener

@@ -514,12 +513,12 @@
      * equivalent to:
      * <pre>
      * getDocumentProperties().get(key);
      * </pre>
      *
-     * @param key the non-<code>null</code> property key
-     * @return the value of this property or <code>null</code>
+     * @param key the non-{@code null} property key
+     * @return the value of this property or {@code null}
      * @see #getDocumentProperties
      */
     public final Object getProperty(Object key) {
         return getDocumentProperties().get(key);
     }

@@ -529,14 +528,14 @@
      * A convenience method for storing up a property value.  It is
      * equivalent to:
      * <pre>
      * getDocumentProperties().put(key, value);
      * </pre>
-     * If <code>value</code> is <code>null</code> this method will
+     * If {@code value} is {@code null} this method will
      * remove the property.
      *
-     * @param key the non-<code>null</code> key
+     * @param key the non-{@code null} key
      * @param value the property value
      * @see #getDocumentProperties
      */
     public final void putProperty(Object key, Object value) {
         if (value != null) {

@@ -594,11 +593,11 @@
         }
     }
 
     /**
      * Performs the actual work of the remove. It is assumed the caller
-     * will have obtained a <code>writeLock</code> before invoking this.
+     * will have obtained a {@code writeLock} before invoking this.
      */
     void handleRemove(int offs, int len) throws BadLocationException {
         if (len > 0) {
             if (offs < 0 || (offs + len) > getLength()) {
                 throw new BadLocationException("Invalid remove",

@@ -627,23 +626,23 @@
             }
         }
     }
 
     /**
-     * Deletes the region of text from <code>offset</code> to
-     * <code>offset + length</code>, and replaces it with <code>text</code>.
+     * Deletes the region of text from {@code offset} to
+     * {@code offset + length}, and replaces it with {@code text}.
      * It is up to the implementation as to how this is implemented, some
      * implementations may treat this as two distinct operations: a remove
      * followed by an insert, others may treat the replace as one atomic
      * operation.
      *
      * @param offset index of child element
      * @param length length of text to delete, may be 0 indicating don't
      *               delete anything
-     * @param text text to insert, <code>null</code> indicates no text to insert
+     * @param text text to insert, {@code null} indicates no text to insert
      * @param attrs AttributeSet indicating attributes of inserted text,
-     *              <code>null</code>
+     *              {@code null}
      *              is legal, and typically treated as an empty attributeset,
      *              but exact interpretation is left to the subclass
      * @exception BadLocationException the given position is not a valid
      *            position within the document
      * @since 1.4

@@ -888,11 +887,11 @@
     public abstract Element getDefaultRootElement();
 
     // ---- local methods -----------------------------------------
 
     /**
-     * Returns the <code>FilterBypass</code>. This will create one if one
+     * Returns the {@code FilterBypass}. This will create one if one
      * does not yet exist.
      */
     private DocumentFilter.FilterBypass getFilterBypass() {
         if (filterBypass == null) {
             filterBypass = new DefaultFilterBypass();

@@ -910,12 +909,12 @@
     public Element getBidiRootElement() {
         return bidiRoot;
     }
 
     /**
-     * Returns true if the text in the range <code>p0</code> to
-     * <code>p1</code> is left to right.
+     * Returns true if the text in the range {@code p0} to
+     * {@code p1} is left to right.
      */
     static boolean isLeftToRight(Document doc, int p0, int p1) {
         if (Boolean.TRUE.equals(doc.getProperty(I18NProperty))) {
             if (doc instanceof AbstractDocument) {
                 AbstractDocument adoc = (AbstractDocument) doc;

@@ -1296,32 +1295,32 @@
      * being called as part of an existing modification or
      * if a lock needs to be acquired and a new transaction
      * started.
      *
      * @return the thread actively modifying the document
-     *  or <code>null</code> if there are no modifications in progress
+     *  or {@code null} if there are no modifications in progress
      */
     protected final synchronized Thread getCurrentWriter() {
         return currWriter;
     }
 
     /**
      * Acquires a lock to begin mutating the document this lock
      * protects.  There can be no writing, notification of changes, or
      * reading going on in order to gain the lock.  Additionally a thread is
-     * allowed to gain more than one <code>writeLock</code>,
-     * as long as it doesn't attempt to gain additional <code>writeLock</code>s
+     * allowed to gain more than one {@code writeLock},
+     * as long as it doesn't attempt to gain additional {@code writeLock}s
      * from within document notification.  Attempting to gain a
-     * <code>writeLock</code> from within a DocumentListener notification will
-     * result in an <code>IllegalStateException</code>.  The ability
-     * to obtain more than one <code>writeLock</code> per thread allows
+     * {@code writeLock} from within a DocumentListener notification will
+     * result in an {@code IllegalStateException}.  The ability
+     * to obtain more than one {@code writeLock} per thread allows
      * subclasses to gain a writeLock, perform a number of operations, then
      * release the lock.
      * <p>
-     * Calls to <code>writeLock</code>
-     * must be balanced with calls to <code>writeUnlock</code>, else the
-     * <code>Document</code> will be left in a locked state so that no
+     * Calls to {@code writeLock}
+     * must be balanced with calls to {@code writeUnlock}, else the
+     * {@code Document} will be left in a locked state so that no
      * reading or writing can be done.
      *
      * @exception IllegalStateException thrown on illegal lock
      *  attempt.  If the document is implemented properly, this can
      *  only happen if a document listener attempts to mutate the

@@ -1351,11 +1350,11 @@
             throw new Error("Interrupted attempt to acquire write lock");
         }
     }
 
     /**
-     * Releases a write lock previously obtained via <code>writeLock</code>.
+     * Releases a write lock previously obtained via {@code writeLock}.
      * After decrementing the lock count if there are no outstanding locks
      * this will allow a new writer, or readers.
      *
      * @see #writeLock
      */

@@ -1372,11 +1371,11 @@
      * document.  There can be multiple readers at the same time.
      * Writing blocks the readers until notification of the change
      * to the listeners has been completed.  This method should
      * be used very carefully to avoid unintended compromise
      * of the document.  It should always be balanced with a
-     * <code>readUnlock</code>.
+     * {@code readUnlock}.
      *
      * @see #readUnlock
      */
     public final synchronized void readLock() {
         try {

@@ -1475,11 +1474,11 @@
     // ----- member variables ------------------------------------------
 
     private transient int numReaders;
     private transient Thread currWriter;
     /**
-     * The number of writers, all obtained from <code>currWriter</code>.
+     * The number of writers, all obtained from {@code currWriter}.
      */
     private transient int numWriters;
     /**
      * True will notifying listeners.
      */

@@ -1615,12 +1614,12 @@
          * Inserts a string of characters into the sequence.
          *
          * @param where   offset into the sequence to make the insertion &gt;= 0
          * @param str     string to insert
          * @return  if the implementation supports a history mechanism,
-         *    a reference to an <code>Edit</code> implementation will be returned,
-         *    otherwise returns <code>null</code>
+         *    a reference to an {@code Edit} implementation will be returned,
+         *    otherwise returns {@code null}
          * @exception BadLocationException  thrown if the area covered by
          *   the arguments is not contained in the character sequence
          */
         public UndoableEdit insertString(int where, String str) throws BadLocationException;
 

@@ -1672,11 +1671,11 @@
      *
      * The Element implementations provided by this class use
      * this interface to provide their MutableAttributeSet
      * implementations, so that different AttributeSet compression
      * techniques can be employed.  The method
-     * <code>getAttributeContext</code> should be implemented to
+     * {@code getAttributeContext} should be implemented to
      * return the object responsible for implementing the desired
      * compression technique.
      *
      * @see StyleContext
      */

@@ -1765,11 +1764,11 @@
      * Serialized objects of this class will not be compatible with
      * future Swing releases. The current serialization support is
      * appropriate for short term storage or RMI between applications running
      * the same version of Swing.  As of 1.4, support for long term storage
      * of all JavaBeans&trade;
-     * has been added to the <code>java.beans</code> package.
+     * has been added to the {@code java.beans} package.
      * Please see {@link java.beans.XMLEncoder}.
      */
     @SuppressWarnings("serial") // Same-version serialization only
     public abstract class AbstractElement implements Element, MutableAttributeSet, Serializable, TreeNode {
 

@@ -1953,11 +1952,11 @@
         /**
          * Gets the resolving parent.
          * If not overridden, the resolving parent defaults to
          * the parent element.
          *
-         * @return the attributes from the parent, <code>null</code> if none
+         * @return the attributes from the parent, {@code null} if none
          * @see AttributeSet#getResolveParent
          */
         public AttributeSet getResolveParent() {
             AttributeSet a = attributes.getResolveParent();
             if ((a == null) && (parent != null)) {

@@ -2147,41 +2146,41 @@
         public abstract boolean isLeaf();
 
         // --- TreeNode methods -------------------------------------
 
         /**
-         * Returns the child <code>TreeNode</code> at index
-         * <code>childIndex</code>.
+         * Returns the child {@code TreeNode} at index
+         * {@code childIndex}.
          */
         public TreeNode getChildAt(int childIndex) {
             return (TreeNode)getElement(childIndex);
         }
 
         /**
-         * Returns the number of children <code>TreeNode</code>'s
+         * Returns the number of children {@code TreeNode}'s
          * receiver contains.
-         * @return the number of children <code>TreeNodews</code>'s
+         * @return the number of children {@code TreeNodews}'s
          * receiver contains
          */
         public int getChildCount() {
             return getElementCount();
         }
 
         /**
-         * Returns the parent <code>TreeNode</code> of the receiver.
-         * @return the parent <code>TreeNode</code> of the receiver
+         * Returns the parent {@code TreeNode} of the receiver.
+         * @return the parent {@code TreeNode} of the receiver
          */
         public TreeNode getParent() {
             return (TreeNode)getParentElement();
         }
 
         /**
-         * Returns the index of <code>node</code> in the receivers children.
-         * If the receiver does not contain <code>node</code>, -1 will be
+         * Returns the index of {@code node} in the receivers children.
+         * If the receiver does not contain {@code node}, -1 will be
          * returned.
          * @param node the location of interest
-         * @return the index of <code>node</code> in the receiver's
+         * @return the index of {@code node} in the receiver's
          * children, or -1 if absent
          */
         public int getIndex(TreeNode node) {
             for(int counter = getChildCount() - 1; counter >= 0; counter--)
                 if(getChildAt(counter) == node)

@@ -2196,12 +2195,12 @@
         public abstract boolean getAllowsChildren();
 
 
         /**
          * Returns the children of the receiver as an
-         * <code>Enumeration</code>.
-         * @return the children of the receiver as an <code>Enumeration</code>
+         * {@code Enumeration}.
+         * @return the children of the receiver as an {@code Enumeration}
          */
         public abstract Enumeration<TreeNode> children();
 
 
         // --- serialization ---------------------------------------------

@@ -2235,11 +2234,11 @@
      * Serialized objects of this class will not be compatible with
      * future Swing releases. The current serialization support is
      * appropriate for short term storage or RMI between applications running
      * the same version of Swing.  As of 1.4, support for long term storage
      * of all JavaBeans&trade;
-     * has been added to the <code>java.beans</code> package.
+     * has been added to the {@code java.beans} package.
      * Please see {@link java.beans.XMLEncoder}.
      */
     @SuppressWarnings("serial") // Same-version serialization only
     public class BranchElement extends AbstractElement {
 

@@ -2459,11 +2458,11 @@
         }
 
 
         /**
          * Returns the children of the receiver as an
-         * <code>Enumeration</code>.
+         * {@code Enumeration}.
          * @return the children of the receiver
          */
         public Enumeration<TreeNode> children() {
             if(nchildren == 0)
                 return null;

@@ -2490,11 +2489,11 @@
      * Serialized objects of this class will not be compatible with
      * future Swing releases. The current serialization support is
      * appropriate for short term storage or RMI between applications running
      * the same version of Swing.  As of 1.4, support for long term storage
      * of all JavaBeans&trade;
-     * has been added to the <code>java.beans</code> package.
+     * has been added to the {@code java.beans} package.
      * Please see {@link java.beans.XMLEncoder}.
      *
      * @see     Element
      */
     @SuppressWarnings("serial") // Same-version serialization only

@@ -2613,11 +2612,11 @@
         }
 
 
         /**
          * Returns the children of the receiver as an
-         * <code>Enumeration</code>.
+         * {@code Enumeration}.
          * @return the children of the receiver
          */
         @Override
         public Enumeration<TreeNode> children() {
             return null;
< prev index next >