javax.swing.text
Class AbstractDocument

java.lang.Object   
  javax.swing.text.AbstractDocument

All Implemented Interfaces:

Serializable , Document

Direct Known Subclasses:

DefaultStyledDocument , PlainDocument

public abstract class AbstractDocument
extends Object   
implements Document   , Serializable   

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 aquired 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 independant 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^TM has been added to the java.beans package. Please see XMLEncoder .

See Also:

Serialized Form

Nested Class Summary

class	AbstractDocument.AbstractElement Implements the abstract part of an element.
static interface	AbstractDocument.AttributeContext An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
class	AbstractDocument.BranchElement Implements a composite element that contains other elements.
static interface	AbstractDocument.Content Interface to describe a sequence of character content that can be edited.
class	AbstractDocument.DefaultDocumentEvent Stores document changes as the document is being modified.
static class	AbstractDocument.ElementEdit An implementation of ElementChange that can be added to the document event.
class	AbstractDocument.LeafElement Implements an element that directly represents content of some kind.

Field Summary

protected static String	BAD_LOCATION Error message to indicate a bad location.
static String	BidiElementName Name of elements used to hold a unidirectional run
static String	ContentElementName Name of elements used to represent content
static String	ElementNameAttribute Name of the attribute used to specify element names.
protected EventListenerList	listenerList The event listener list for the document.
static String	ParagraphElementName Name of elements used to represent paragraphs
static String	SectionElementName Name of elements used to hold sections (lines/paragraphs).

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty , TitleProperty

Constructor Summary

protected	AbstractDocument (AbstractDocument.Content data) Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
protected	AbstractDocument (AbstractDocument.Content data, AbstractDocument.AttributeContext context) Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.

Method Summary

void	addDocumentListener (DocumentListener listener) Adds a document listener for notification of any changes.
void	addUndoableEditListener (UndoableEditListener listener) Adds an undo listener for notification of any changes.
protected Element	createBranchElement (Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected Element	createLeafElement (Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element.
Position	createPosition (int offs) Returns a position that will track change as the document is altered.
void	dump (PrintStream out) Gives a diagnostic dump.
protected void	fireChangedUpdate (DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireInsertUpdate (DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireRemoveUpdate (DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireUndoableEditUpdate (UndoableEditEvent e) Notifies all listeners that have registered interest for notification on this event type.
int	getAsynchronousLoadPriority () Gets the asynchronous loading priority.
protected AbstractDocument.AttributeContext	getAttributeContext () Fetches the context for managing attributes.
Element	getBidiRootElement () Returns the root element of the bidirectional structure for this document.
protected AbstractDocument.Content	getContent () Gets the content for the document.
protected Thread	getCurrentWriter () Fetches the current writing thread if there is one.
abstract Element	getDefaultRootElement () Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
DocumentFilter	getDocumentFilter () Returns the DocumentFilter that is responsible for filtering of insertion/removal.
DocumentListener []	getDocumentListeners () Returns an array of all the document listeners registered on this document.
Dictionary <Object ,Object >	getDocumentProperties () Supports managing a set of properties.
Position	getEndPosition () Returns a position that represents the end of the document.
int	getLength () Returns the length of the data.
<T extends EventListener > T[]	getListeners (Class <T> listenerType) Returns an array of all the objects currently registered as FooListeners upon this document.
abstract Element	getParagraphElement (int pos) Get the paragraph element containing the given position.
Object	getProperty (Object key) A convenience method for looking up a property value.
Element []	getRootElements () Gets all root elements defined.
Position	getStartPosition () Returns a position that represents the start of the document.
String	getText (int offset, int length) Gets a sequence of text from the document.
void	getText (int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
UndoableEditListener []	getUndoableEditListeners () Returns an array of all the undoable edit listeners registered on this document.
void	insertString (int offs, String str, AttributeSet a) Inserts some content into the document.
protected void	insertUpdate (AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void	postRemoveUpdate (AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.
void	putProperty (Object key, Object value) A convenience method for storing up a property value.
void	readLock () Acquires a lock to begin reading some state from the document.
void	readUnlock () Does a read unlock.
void	remove (int offs, int len) Removes some content from the document.
void	removeDocumentListener (DocumentListener listener) Removes a document listener.
void	removeUndoableEditListener (UndoableEditListener listener) Removes an undo listener.
protected void	removeUpdate (AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.
void	render (Runnable r) This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.
void	replace (int offset, int length, String text, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
void	setAsynchronousLoadPriority (int p) Sets the asynchronous loading priority.
void	setDocumentFilter (DocumentFilter filter) Sets the DocumentFilter.
void	setDocumentProperties (Dictionary <Object ,Object > x) Replaces the document properties dictionary for this document.
protected void	writeLock () Acquires a lock to begin mutating the document this lock protects.
protected void	writeUnlock () Releases a write lock previously obtained via writeLock.

Methods inherited from class java.lang.Object