< 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™
- * 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 >= 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™
- * 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™
- * 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™
- * 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 >