javax.swing.text

Class AbstractDocument

public abstract class AbstractDocument extends Object implements Document, Serializable

An abstract base implementation for the {@link Document} interface. This class provides some common functionality for all Elements, most notably it implements a locking mechanism to make document modification thread-safe.
Nested Class Summary
abstract classAbstractDocument.AbstractElement
An abstract base implementation of the {@link Element} interface.
interfaceAbstractDocument.AttributeContext
Defines a set of methods for managing text attributes for one or more Documents.
classAbstractDocument.BranchElement
An implementation of {@link Element} to represent composite Elements that contain other Elements.
interfaceAbstractDocument.Content
A sequence of data that can be edited.
classAbstractDocument.DefaultDocumentEvent
Stores the changes when a Document is beeing modified.
static classAbstractDocument.ElementEdit
An implementation of {@link DocumentEvent.ElementChange} to be added to {@link DefaultDocumentEvent}s.
classAbstractDocument.LeafElement
An implementation of {@link Element} that represents a leaf in the document structure.
Field Summary
protected static StringBAD_LOCATION
Standard error message to indicate a bad location.
static StringBidiElementName
Standard name for unidirectional Elements.
static StringContentElementName
Standard name for content Elements.
static StringElementNameAttribute
Attribute key for storing the element name.
protected EventListenerListlistenerList
Manages event listeners for this Document.
static StringParagraphElementName
Standard name for paragraph Elements.
static StringSectionElementName
Standard name for section Elements.
Constructor Summary
protected AbstractDocument(AbstractDocument.Content doc)
Creates a new AbstractDocument with the specified {@link Content} model.
protected AbstractDocument(AbstractDocument.Content doc, AbstractDocument.AttributeContext ctx)
Creates a new AbstractDocument with the specified {@link Content} model and {@link AttributeContext}.
Method Summary
voidaddDocumentListener(DocumentListener listener)
Adds a DocumentListener object to this document.
voidaddUndoableEditListener(UndoableEditListener listener)
Adds an {@link UndoableEditListener} to this Document.
protected ElementcreateBranchElement(Element parent, AttributeSet attributes)
Creates and returns a branch element with the specified parent and attributes.
protected ElementcreateLeafElement(Element parent, AttributeSet attributes, int start, int end)
Creates and returns a leaf element with the specified parent and attributes.
PositioncreatePosition(int offset)
Creates a {@link Position} that keeps track of the location at the specified offset.
voiddump(PrintStream out)
Dumps diagnostic information to the specified PrintStream.
protected voidfireChangedUpdate(DocumentEvent event)
Notifies all registered listeners when the document model changes.
protected voidfireInsertUpdate(DocumentEvent event)
Notifies all registered listeners when content is inserted in the document model.
protected voidfireRemoveUpdate(DocumentEvent event)
Notifies all registered listeners when content is removed from the document model.
protected voidfireUndoableEditUpdate(UndoableEditEvent event)
Notifies all registered listeners when an UndoableEdit has been performed on this Document.
intgetAsynchronousLoadPriority()
Returns the asynchronous loading priority.
protected AbstractDocument.AttributeContextgetAttributeContext()
Returns the {@link AttributeContext} used in this Document.
ElementgetBidiRootElement()
Returns the root element for bidirectional content.
protected AbstractDocument.ContentgetContent()
Returns the {@link Content} model for this Document
protected ThreadgetCurrentWriter()
Returns the thread that currently modifies this Document if there is one, otherwise null.
abstract ElementgetDefaultRootElement()
Returns the default root {@link Element} of this Document.
DocumentFiltergetDocumentFilter()
Returns the currently installed {@link DocumentFilter} for this Document.
DocumentListener[]getDocumentListeners()
Returns all registered DocumentListeners.
Dictionary<Object,Object>getDocumentProperties()
Returns the properties of this Document.
PositiongetEndPosition()
Returns a {@link Position} which will always mark the end of the Document.
intgetLength()
Returns the length of this Document's content.
<T extends EventListener> T[]getListeners(Class<T> listenerType)
Returns all registered listeners of a given listener type.
abstract ElementgetParagraphElement(int pos)
Returns the paragraph {@link Element} that holds the specified position.
ObjectgetProperty(Object key)
Returns a property from this Document's property list.
Element[]getRootElements()
Returns all root elements of this Document.
PositiongetStartPosition()
Returns a {@link Position} which will always mark the beginning of the Document.
StringgetText(int offset, int length)
Returns a piece of this Document's content.
voidgetText(int offset, int length, Segment segment)
Fetches a piece of this Document's content and stores it in the given {@link Segment}.
UndoableEditListener[]getUndoableEditListeners()
Returns all registered {@link UndoableEditListener}s.
voidinsertString(int offset, String text, AttributeSet attributes)
Inserts a String into this Document at the specified position and assigning the specified attributes to it.
protected voidinsertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Called to indicate that text has been inserted into this Document.
protected voidpostRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called after some content has been removed from this Document.
voidputProperty(Object key, Object value)
Stores a property in this Document's property list.
voidreadLock()
Blocks until a read lock can be obtained.
voidreadUnlock()
Releases the read lock.
voidremove(int offset, int length)
Removes a piece of content from this Document.
voidremoveDocumentListener(DocumentListener listener)
Removes a DocumentListener object from this document.
voidremoveUndoableEditListener(UndoableEditListener listener)
Removes an {@link UndoableEditListener} from this Document.
protected voidremoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called before some content gets removed from this Document.
voidrender(Runnable runnable)
Called to render this Document visually.
voidreplace(int offset, int length, String text, AttributeSet attributes)
Replaces a piece of content in this Document with another piece of content.
voidsetAsynchronousLoadPriority(int p)
Sets the asynchronous loading priority for this Document.
voidsetDocumentFilter(DocumentFilter filter)
Sets the {@link DocumentFilter} for this Document.
voidsetDocumentProperties(Dictionary<Object,Object> p)
Sets the properties of this Document.
protected voidwriteLock()
Blocks until a write lock can be obtained.
protected voidwriteUnlock()
Releases the write lock.

Field Detail

BAD_LOCATION

protected static final String BAD_LOCATION
Standard error message to indicate a bad location.

BidiElementName

public static final String BidiElementName
Standard name for unidirectional Elements.

ContentElementName

public static final String ContentElementName
Standard name for content Elements. These are usually {@link LeafElement}s.

ElementNameAttribute

public static final String ElementNameAttribute
Attribute key for storing the element name.

listenerList

protected EventListenerList listenerList
Manages event listeners for this Document.

ParagraphElementName

public static final String ParagraphElementName
Standard name for paragraph Elements. These are usually {@link BranchElement}s.

SectionElementName

public static final String SectionElementName
Standard name for section Elements. These are usually {@link DefaultStyledDocument.SectionElement}s.

Constructor Detail

AbstractDocument

protected AbstractDocument(AbstractDocument.Content doc)
Creates a new AbstractDocument with the specified {@link Content} model.

Parameters: doc the Content model to be used in this Document

See Also: GapContent StringContent

AbstractDocument

protected AbstractDocument(AbstractDocument.Content doc, AbstractDocument.AttributeContext ctx)
Creates a new AbstractDocument with the specified {@link Content} model and {@link AttributeContext}.

Parameters: doc the Content model to be used in this Document ctx the AttributeContext to use

See Also: GapContent StringContent

Method Detail

addDocumentListener

public void addDocumentListener(DocumentListener listener)
Adds a DocumentListener object to this document.

Parameters: listener the listener to add

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Adds an {@link UndoableEditListener} to this Document.

Parameters: listener the listener to add

createBranchElement

protected Element createBranchElement(Element parent, AttributeSet attributes)
Creates and returns a branch element with the specified parent and attributes. Note that the new Element is linked to the parent Element through {@link Element#getParentElement}, but it is not yet added to the parent Element as child.

Parameters: parent the parent Element for the new branch element attributes the text attributes to be installed in the new element

Returns: the new branch Element

See Also: BranchElement

createLeafElement

protected Element createLeafElement(Element parent, AttributeSet attributes, int start, int end)
Creates and returns a leaf element with the specified parent and attributes. Note that the new Element is linked to the parent Element through {@link Element#getParentElement}, but it is not yet added to the parent Element as child.

Parameters: parent the parent Element for the new branch element attributes the text attributes to be installed in the new element

Returns: the new branch Element

See Also: LeafElement

createPosition

public Position createPosition(int offset)
Creates a {@link Position} that keeps track of the location at the specified offset.

Parameters: offset the location in the document to keep track by the new Position

Returns: the newly created Position

Throws: BadLocationException if offset is not a valid location in the documents content model

dump

public void dump(PrintStream out)
Dumps diagnostic information to the specified PrintStream.

Parameters: out the stream to write the diagnostic information to

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent event)
Notifies all registered listeners when the document model changes.

Parameters: event the DocumentEvent to be fired

fireInsertUpdate

protected void fireInsertUpdate(DocumentEvent event)
Notifies all registered listeners when content is inserted in the document model.

Parameters: event the DocumentEvent to be fired

fireRemoveUpdate

protected void fireRemoveUpdate(DocumentEvent event)
Notifies all registered listeners when content is removed from the document model.

Parameters: event the DocumentEvent to be fired

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent event)
Notifies all registered listeners when an UndoableEdit has been performed on this Document.

Parameters: event the UndoableEditEvent to be fired

getAsynchronousLoadPriority

public int getAsynchronousLoadPriority()
Returns the asynchronous loading priority. Returns -1 if this document should not be loaded asynchronously.

Returns: the asynchronous loading priority

getAttributeContext

protected final AbstractDocument.AttributeContext getAttributeContext()
Returns the {@link AttributeContext} used in this Document.

Returns: the {@link AttributeContext} used in this Document

getBidiRootElement

public Element getBidiRootElement()
Returns the root element for bidirectional content.

Returns: the root element for bidirectional content

getContent

protected final AbstractDocument.Content getContent()
Returns the {@link Content} model for this Document

Returns: the {@link Content} model for this Document

See Also: GapContent StringContent

getCurrentWriter

protected final Thread getCurrentWriter()
Returns the thread that currently modifies this Document if there is one, otherwise null. This can be used to distinguish between a method call that is part of an ongoing modification or if it is a separate modification for which a new lock must be aquired.

Returns: the thread that currently modifies this Document if there is one, otherwise null

getDefaultRootElement

public abstract Element getDefaultRootElement()
Returns the default root {@link Element} of this Document. Usual Documents only have one root element and return this. However, there may be Document implementations that support multiple root elements, they have to return a default root element here.

Returns: the default root {@link Element} of this Document

getDocumentFilter

public DocumentFilter getDocumentFilter()
Returns the currently installed {@link DocumentFilter} for this Document.

Returns: the currently installed {@link DocumentFilter} for this Document

Since: 1.4

getDocumentListeners

public DocumentListener[] getDocumentListeners()
Returns all registered DocumentListeners.

Returns: all registered DocumentListeners

getDocumentProperties

public Dictionary<Object,Object> getDocumentProperties()
Returns the properties of this Document.

Returns: the properties of this Document

getEndPosition

public final Position getEndPosition()
Returns a {@link Position} which will always mark the end of the Document.

Returns: a {@link Position} which will always mark the end of the Document

getLength

public int getLength()
Returns the length of this Document's content.

Returns: the length of this Document's content

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns all registered listeners of a given listener type.

Parameters: listenerType the type of the listeners to be queried

Returns: all registered listeners of the specified type

getParagraphElement

public abstract Element getParagraphElement(int pos)
Returns the paragraph {@link Element} that holds the specified position.

Parameters: pos the position for which to get the paragraph element

Returns: the paragraph {@link Element} that holds the specified position

getProperty

public final Object getProperty(Object key)
Returns a property from this Document's property list.

Parameters: key the key of the property to be fetched

Returns: the property for key or null if there is no such property stored

getRootElements

public Element[] getRootElements()
Returns all root elements of this Document. By default this just returns the single root element returned by {@link #getDefaultRootElement()}. Document implementations that support multiple roots must override this method and return all roots here.

Returns: all root elements of this Document

getStartPosition

public final Position getStartPosition()
Returns a {@link Position} which will always mark the beginning of the Document.

Returns: a {@link Position} which will always mark the beginning of the Document

getText

public String getText(int offset, int length)
Returns a piece of this Document's content.

Parameters: offset the start offset of the content length the length of the content

Returns: the piece of content specified by offset and length

Throws: BadLocationException if offset or offset + length are invalid locations with this Document

getText

public void getText(int offset, int length, Segment segment)
Fetches a piece of this Document's content and stores it in the given {@link Segment}.

Parameters: offset the start offset of the content length the length of the content segment the Segment to store the content in

Throws: BadLocationException if offset or offset + length are invalid locations with this Document

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()
Returns all registered {@link UndoableEditListener}s.

Returns: all registered {@link UndoableEditListener}s

insertString

public void insertString(int offset, String text, AttributeSet attributes)
Inserts a String into this Document at the specified position and assigning the specified attributes to it.

If a {@link DocumentFilter} is installed in this document, the corresponding method of the filter object is called.

The method has no effect when text is null or has a length of zero.

Parameters: offset the location at which the string should be inserted text the content to be inserted attributes the text attributes to be assigned to that string

Throws: BadLocationException if offset is not a valid location in this Document

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Called to indicate that text has been inserted into this Document. The default implementation does nothing. This method is executed within a write lock.

Parameters: chng the DefaultDocumentEvent describing the change attr the attributes of the changed content

postRemoveUpdate

protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called after some content has been removed from this Document. The default implementation does nothing. This method is executed within a write lock.

Parameters: chng the DefaultDocumentEvent describing the change

putProperty

public final void putProperty(Object key, Object value)
Stores a property in this Document's property list.

Parameters: key the key of the property to be stored value the value of the property to be stored

readLock

public final void readLock()
Blocks until a read lock can be obtained. Must block if there is currently a writer modifying the Document.

readUnlock

public final void readUnlock()
Releases the read lock. If this was the only reader on this Document, writing may begin now.

remove

public void remove(int offset, int length)
Removes a piece of content from this Document.

If a {@link DocumentFilter} is installed in this document, the corresponding method of the filter object is called. The DocumentFilter is called even if length is zero. This is different from {@link #replace}.

Note: When length is zero or below the call is not forwarded to the underlying {@link AbstractDocument.Content} instance of this document and no exception is thrown.

Parameters: offset the start offset of the fragment to be removed length the length of the fragment to be removed

Throws: BadLocationException if offset or offset + length or invalid locations within this document

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)
Removes a DocumentListener object from this document.

Parameters: listener the listener to remove

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Removes an {@link UndoableEditListener} from this Document.

Parameters: listener the listener to remove

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called before some content gets removed from this Document. The default implementation does nothing but may be overridden by subclasses to modify the Document structure in response to a remove request. The method is executed within a write lock.

Parameters: chng the DefaultDocumentEvent describing the change

render

public void render(Runnable runnable)
Called to render this Document visually. It obtains a read lock, ensuring that no changes will be made to the document during the rendering process. It then calls the {@link Runnable#run()} method on runnable. This method must not attempt to modifiy the Document, since a deadlock will occur if it tries to obtain a write lock. When the {@link Runnable#run()} method completes (either naturally or by throwing an exception), the read lock is released. Note that there is nothing in this method related to the actual rendering. It could be used to execute arbitrary code within a read lock.

Parameters: runnable the {@link Runnable} to execute

replace

public void replace(int offset, int length, String text, AttributeSet attributes)
Replaces a piece of content in this Document with another piece of content.

If a {@link DocumentFilter} is installed in this document, the corresponding method of the filter object is called.

The method has no effect if length is zero (and only zero) and, at the same time, text is null or has zero length.

Parameters: offset the start offset of the fragment to be removed length the length of the fragment to be removed text the text to replace the content with attributes the text attributes to assign to the new content

Throws: BadLocationException if offset or offset + length or invalid locations within this document

Since: 1.4

setAsynchronousLoadPriority

public void setAsynchronousLoadPriority(int p)
Sets the asynchronous loading priority for this Document. A value of -1 indicates that this Document should be loaded synchronously.

Parameters: p the asynchronous loading priority to set

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)
Sets the {@link DocumentFilter} for this Document.

Parameters: filter the DocumentFilter to set

Since: 1.4

setDocumentProperties

public void setDocumentProperties(Dictionary<Object,Object> p)
Sets the properties of this Document.

Parameters: p the document properties to set

writeLock

protected final void writeLock()
Blocks until a write lock can be obtained. Must wait if there are readers currently reading or another thread is currently writing.

writeUnlock

protected final void writeUnlock()
Releases the write lock. This allows waiting readers or writers to obtain the lock.