OpenJDK 27 · javax.swing.text.AbstractDocument · APIdia, the JavaDoc alternative

An implementation of the document interface to serve as a basis for implementing various kinds of documents. At this level there is very little policy, so there is a corresponding increase in difficulty of use.

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 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 until the notification has finished. The notification is a beans event notification which does not allow any further mutations until all listeners have been notified.

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 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.

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 repaint and revalidate methods on JComponent are safe.

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, 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 getParagraphElement(getLength()).getEndOffset() == getLength() + 1.

Warning

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 java.beans package. Please see java.beans.XMLEncoder.

Modifier and Type	Class and Description
public abstract class	AbstractDocument.AbstractElement Implements the abstract part of an element.
public static interface	AbstractDocument.AttributeContext An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
pack-priv class	AbstractDocument.BidiElement Represents an element of the bidirectional element structure.
pack-priv class	AbstractDocument.BidiRootElement Represents the root element of the bidirectional element structure.
public class	AbstractDocument.BranchElement Implements a composite element that contains other elements.
public static interface	AbstractDocument.Content Interface to describe a sequence of character content that can be edited.
public class	AbstractDocument.DefaultDocumentEvent Stores document changes as the document is being modified.
pack-priv class	AbstractDocument.DefaultDocumentEventUndoableWrapper
private class	AbstractDocument.DefaultFilterBypass
public static class	AbstractDocument.ElementEdit An implementation of ElementChange that can be added to the document event.
public class	AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
pack-priv class	AbstractDocument.UndoRedoDocumentEvent This event used when firing document changes while Undo/Redo operations.

Modifier and Type	Field and Description
pack-priv static final String	AsyncLoadPriority Document property that indicates asynchronous loading is desired, with the thread priority given as the value.
protected static final String	BAD_LOCATION Error message to indicate a bad location.
private static final String	BAD_LOCK_STATE
public static final String	BidiElementName Name of elements used to hold a unidirectional run
private transient AbstractDocument.BranchElement	bidiRoot The root of the bidirectional structure for this document.
public static final String	ContentElementName Name of elements used to represent content
private AbstractDocument.AttributeContext	context Factory for the attributes.
private transient Thread	currWriter
private AbstractDocument.Content	data Where the text is actually stored, and a set of marks that track change as the document is edited are managed.
private static Boolean	defaultI18NProperty
private DocumentFilter	documentFilter Filter for inserting/removing of text.
private Dictionary<Object, Object>	documentProperties Storage for document-wide properties.
public static final String	ElementNameAttribute Name of the attribute used to specify element names.
private transient DocumentFilter.FilterBypass	filterBypass Used by DocumentFilter to do actual insert/remove.
pack-priv static final String	I18NProperty Document property that indicates whether internationalization functions such as text reordering or reshaping should be performed.
protected EventListenerList	listenerList The event listener list for the document.
pack-priv static final Object	MultiByteProperty Document property that indicates if a character has been inserted into the document that is more than one byte long.
private transient boolean	notifyingListeners True will notifying listeners.
private transient int	numReaders
private transient int	numWriters The number of writers, all obtained from `currWriter`.
public static final String	ParagraphElementName Name of elements used to represent paragraphs
public static final String	SectionElementName Name of elements used to hold sections (lines/paragraphs).

Access	Constructor and Description
protected	AbstractDocument(AbstractDocument.Content the content data) Constructs a new `AbstractDocument`, wrapped around some specified content storage mechanism.
protected	AbstractDocument(AbstractDocument.Content the content data, AbstractDocument.AttributeContext the attribute context context) Constructs a new `AbstractDocument`, wrapped around some specified content storage mechanism.

Method Summary

Modifier and Type	Method and Description
public void	addDocumentListener(DocumentListener the `DocumentListener` to add listener) Implements javax.swing.text.Document.addDocumentListener. Adds a document listener for notification of any changes.
public void	addUndoableEditListener(UndoableEditListener the `UndoableEditListener` to add listener) Implements javax.swing.text.Document.addUndoableEditListener. Adds an undo listener for notification of any changes.
private byte[]	calculateBidiLevels(int firstPStart, int lastPEnd) Calculate the levels array for a range of paragraphs.
protected Element	Returns: the element createBranchElement(Element the parent element parent, AttributeSet the attributes a) Creates a document branch element, that can contain other elements.
protected Element	Returns: the new element createLeafElement(Element the parent element parent, AttributeSet the attributes for the element a, int the beginning of the range >= 0 p0, int the end of the range >= p0 p1) Creates a document leaf element.
public synchronized Position	Returns: the position createPosition(int the position in the model >= 0 offs) Implements javax.swing.text.Document.createPosition. Returns a position that will track change as the document is altered.
public void	dump(PrintStream the output stream out) Gives a diagnostic dump.
protected void	fireChangedUpdate(DocumentEvent the event e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireInsertUpdate(DocumentEvent the event e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireRemoveUpdate(DocumentEvent the event e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireUndoableEditUpdate(UndoableEditEvent the event e) Notifies all listeners that have registered interest for notification on this event type.
public int	Returns: the asynchronous loading priority, or `-1` if the document should not be loaded asynchronously getAsynchronousLoadPriority() Gets the asynchronous loading priority.
protected final AbstractDocument.AttributeContext	Returns: the context getAttributeContext() Fetches the context for managing attributes.
public Element	Returns: the root element of the bidirectional structure for this document getBidiRootElement() Returns the root element of the bidirectional structure for this document.
protected final AbstractDocument.Content	Returns: the content getContent() Gets the content for the document.
protected final synchronized Thread	Returns: the thread actively modifying the document or `null` if there are no modifications in progress getCurrentWriter() Fetches the current writing thread if there is one.
public abstract Element	Returns: the root element getDefaultRootElement() Redeclares javax.swing.text.Document.getDefaultRootElement. Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
public DocumentFilter	Returns: the DocumentFilter getDocumentFilter() Returns the `DocumentFilter` that is responsible for filtering of insertion/removal.
public DocumentListener[]	Returns: all of this document's `DocumentListener`s or an empty array if no document listeners are currently registered getDocumentListeners() Returns an array of all the document listeners registered on this document.
public Dictionary<Object, Object>	Returns: a non-`null` `Dictionary` getDocumentProperties() Supports managing a set of properties.
public final Position	Returns: the position getEndPosition() Implements javax.swing.text.Document.getEndPosition. Returns a position that represents the end of the document.
private DocumentFilter.FilterBypass	getFilterBypass() Returns the `FilterBypass`.
public int	Returns: the length >= 0 getLength() Implements javax.swing.text.Document.getLength. Returns the length of the data.
public < the listener type T extends EventListener> T[]	Returns: an array of all objects registered as `FooListener`s on this component, or an empty array if no such listeners have been added getListeners(Class<T> the type of listeners requested listenerType) Returns an array of all the objects currently registered as `FooListener`s upon this document.
public abstract Element	Returns: the element getParagraphElement(int the starting offset >= 0 pos) Get the paragraph element containing the given position.
public final Object	Returns: the value of this property or `null` getProperty(Object the non-`null` property key key) Implements javax.swing.text.Document.getProperty. A convenience method for looking up a property value.
public Element[]	Returns: the root element getRootElements() Implements javax.swing.text.Document.getRootElements. Gets all root elements defined.
public final Position	Returns: the position getStartPosition() Implements javax.swing.text.Document.getStartPosition. Returns a position that represents the start of the document.
public String	Returns: the text getText(int the starting offset >= 0 offset, int the number of characters to retrieve >= 0 length) Implements javax.swing.text.Document.getText. Gets a sequence of text from the document.
public void	getText(int the starting offset >= 0 offset, int the number of characters to retrieve >= 0 length, Segment the Segment object to retrieve the text into txt) Implements javax.swing.text.Document.getText. Fetches the text contained within the given portion of the document.
public UndoableEditListener[]	Returns: all of this document's `UndoableEditListener`s or an empty array if no undoable edit listeners are currently registered getUndoableEditListeners() Returns an array of all the undoable edit listeners registered on this document.
private void	handleInsertString(int offs, String str, AttributeSet a) Performs the actual work of inserting the text; it is assumed the caller has obtained a write lock before invoking this.
pack-priv void	handleRemove(int offs, int len) Performs the actual work of the remove.
public void	insertString(int the starting offset >= 0 offs, String the string to insert; does nothing with null/empty strings str, AttributeSet the attributes for the inserted content a) Implements javax.swing.text.Document.insertString. Inserts some content into the document.
protected void	insertUpdate(AbstractDocument.DefaultDocumentEvent a description of the change chng, AttributeSet the attributes for the change attr) Updates document structure as a result of text insertion.
pack-priv static boolean	isLeftToRight(Document doc, int p0, int p1) Returns true if the text in the range `p0` to `p1` is left to right.
protected void	postRemoveUpdate(AbstractDocument.DefaultDocumentEvent a description of the change chng) Updates any document structure as a result of text removal.
public final void	putProperty(Object the non-`null` key key, Object the property value value) Implements javax.swing.text.Document.putProperty. A convenience method for storing up a property value.
public final synchronized void	readLock() Acquires a lock to begin reading some state from the document.
private void	readObject(ObjectInputStream s)
public final synchronized void	readUnlock() Does a read unlock.
public void	remove(int the starting offset >= 0 offs, int the number of characters to remove >= 0 len) Implements javax.swing.text.Document.remove. Removes some content from the document.
public void	removeDocumentListener(DocumentListener the `DocumentListener` to remove listener) Implements javax.swing.text.Document.removeDocumentListener. Removes a document listener.
public void	removeUndoableEditListener(UndoableEditListener the `UndoableEditListener` to remove listener) Implements javax.swing.text.Document.removeUndoableEditListener. Removes an undo listener.
protected void	removeUpdate(AbstractDocument.DefaultDocumentEvent a description of the change chng) Updates any document structure as a result of text removal.
public void	render(Runnable the renderer to execute r) Implements javax.swing.text.Document.render. This allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously.
public void	replace(int index of child element offset, int length of text to delete, may be 0 indicating don't delete anything length, String text to insert, `null` indicates no text to insert text, AttributeSet AttributeSet indicating attributes of inserted text, `null` is legal, and typically treated as an empty attributeset, but exact interpretation is left to the subclass attrs) Deletes the region of text from `offset` to `offset + length`, and replaces it with `text`.
public void	setAsynchronousLoadPriority(int the new asynchronous loading priority; a value less than zero indicates that the document should not be loaded asynchronously p) Sets the asynchronous loading priority.
public void	setDocumentFilter(DocumentFilter the `DocumentFilter` used to constrain text filter) Sets the `DocumentFilter`.
public void	setDocumentProperties(Dictionary<Object, Object> the new dictionary x) Replaces the document properties dictionary for this document.
pack-priv void	updateBidi(AbstractDocument.DefaultDocumentEvent chng) Update the bidi element structure as a result of the given change to the document.
protected final synchronized void	writeLock() Acquires a lock to begin mutating the document this lock protects.
protected final synchronized void	writeUnlock() Releases a write lock previously obtained via `writeLock`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public abstract Class AbstractDocument

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary