javax.swing.text
Class AbstractDocument

java.lang.Object
  extended by javax.swing.text.AbstractDocument
All Implemented Interfaces:
Serializable, Document
Direct Known Subclasses:
DefaultStyledDocument, PlainDocument

public abstract class AbstractDocument
extends Object
implements Document, Serializable

An abstract base implementation for the Document interface. This class provides some common functionality for all Elements, most notably it implements a locking mechanism to make document modification thread-safe.

See Also:
Serialized Form

Nested Class Summary
 class AbstractDocument.AbstractElement
          An abstract base implementation of the Element interface.
static interface AbstractDocument.AttributeContext
          Defines a set of methods for managing text attributes for one or more Documents.
 class AbstractDocument.BranchElement
          An implementation of Element to represent composite Elements that contain other Elements.
static interface AbstractDocument.Content
          A sequence of data that can be edited.
 class AbstractDocument.DefaultDocumentEvent
          Stores the changes when a Document is beeing modified.
static class AbstractDocument.ElementEdit
          An implementation of DocumentEvent.ElementChange to be added to AbstractDocument.DefaultDocumentEvents.
 class AbstractDocument.LeafElement
          An implementation of Element that represents a leaf in the document structure.
 
Field Summary
protected static String BAD_LOCATION
          Standard error message to indicate a bad location.
static String BidiElementName
          Standard name for unidirectional Elements.
static String ContentElementName
          Standard name for content Elements.
static String ElementNameAttribute
          Attribute key for storing the element name.
protected  EventListenerList listenerList
          Manages event listeners for this Document.
static String ParagraphElementName
          Standard name for paragraph Elements.
static String SectionElementName
          Standard name for section Elements.
 
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
 
Constructor Summary
protected AbstractDocument(AbstractDocument.Content doc)
          Creates a new AbstractDocument with the specified AbstractDocument.Content model.
protected AbstractDocument(AbstractDocument.Content doc, AbstractDocument.AttributeContext ctx)
          Creates a new AbstractDocument with the specified AbstractDocument.Content model and AbstractDocument.AttributeContext.
 
Method Summary
 void addDocumentListener(DocumentListener listener)
          Adds a DocumentListener object to this document.
 void addUndoableEditListener(UndoableEditListener listener)
          Adds an UndoableEditListener to this Document.
protected  Element createBranchElement(Element parent, AttributeSet attributes)
          Creates and returns a branch element with the specified parent and attributes.
protected  Element createLeafElement(Element parent, AttributeSet attributes, int start, int end)
          Creates and returns a leaf element with the specified parent and attributes.
 Position createPosition(int offset)
          Creates a Position that keeps track of the location at the specified offset.
 void dump(PrintStream out)
          Dumps diagnostic information to the specified PrintStream.
protected  void fireChangedUpdate(DocumentEvent event)
          Notifies all registered listeners when the document model changes.
protected  void fireInsertUpdate(DocumentEvent event)
          Notifies all registered listeners when content is inserted in the document model.
protected  void fireRemoveUpdate(DocumentEvent event)
          Notifies all registered listeners when content is removed from the document model.
protected  void fireUndoableEditUpdate(UndoableEditEvent event)
          Notifies all registered listeners when an UndoableEdit has been performed on this Document.
 int getAsynchronousLoadPriority()
          Returns the asynchronous loading priority.
protected  AbstractDocument.AttributeContext getAttributeContext()
          Returns the AbstractDocument.AttributeContext used in this Document.
 Element getBidiRootElement()
          Returns the root element for bidirectional content.
protected  AbstractDocument.Content getContent()
          Returns the AbstractDocument.Content model for this Document
protected  Thread getCurrentWriter()
          Returns the thread that currently modifies this Document if there is one, otherwise null.
abstract  Element getDefaultRootElement()
          Returns the default root Element of this Document.
 DocumentFilter getDocumentFilter()
          Returns the currently installed DocumentFilter for this Document.
 DocumentListener[] getDocumentListeners()
          Returns all registered DocumentListeners.
 Dictionary<Object,Object> getDocumentProperties()
          Returns the properties of this Document.
 Position getEndPosition()
          Returns a Position which will always mark the end of the Document.
 int getLength()
          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  Element getParagraphElement(int pos)
          Returns the paragraph Element that holds the specified position.
 Object getProperty(Object key)
          Returns a property from this Document's property list.
 Element[] getRootElements()
          Returns all root elements of this Document.
 Position getStartPosition()
          Returns a Position which will always mark the beginning of the Document.
 String getText(int offset, int length)
          Returns a piece of this Document's content.
 void getText(int offset, int length, Segment segment)
          Fetches a piece of this Document's content and stores it in the given Segment.
 UndoableEditListener[] getUndoableEditListeners()
          Returns all registered UndoableEditListeners.
 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.
protected  void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
          Called to indicate that text has been inserted into this Document.
protected  void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
          Called after some content has been removed from this Document.
 void putProperty(Object key, Object value)
          Stores a property in this Document's property list.
 void readLock()
          Blocks until a read lock can be obtained.
 void readUnlock()
          Releases the read lock.
 void remove(int offset, int length)
          Removes a piece of content from this Document.
 void removeDocumentListener(DocumentListener listener)
          Removes a DocumentListener object from this document.
 void removeUndoableEditListener(UndoableEditListener listener)
          Removes an UndoableEditListener from this Document.
protected  void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
          Called before some content gets removed from this Document.
 void render(Runnable runnable)
          Called to render this Document visually.
 void replace(int offset, int length, String text, AttributeSet attributes)
          Replaces a piece of content in this Document with another piece of content.
 void setAsynchronousLoadPriority(int p)
          Sets the asynchronous loading priority for this Document.
 void setDocumentFilter(DocumentFilter filter)
          Sets the DocumentFilter for this Document.
 void setDocumentProperties(Dictionary<Object,Object> p)
          Sets the properties of this Document.
protected  void writeLock()
          Blocks until a write lock can be obtained.
protected  void writeUnlock()
          Releases the write lock.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BAD_LOCATION

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

See Also:
Constant Field Values

BidiElementName

public static final String BidiElementName
Standard name for unidirectional Elements.

See Also:
Constant Field Values

ContentElementName

public static final String ContentElementName
Standard name for content Elements. These are usually AbstractDocument.LeafElements.

See Also:
Constant Field Values

ParagraphElementName

public static final String ParagraphElementName
Standard name for paragraph Elements. These are usually AbstractDocument.BranchElements.

See Also:
Constant Field Values

SectionElementName

public static final String SectionElementName
Standard name for section Elements. These are usually DefaultStyledDocument.SectionElements.

See Also:
Constant Field Values

ElementNameAttribute

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

See Also:
Constant Field Values

listenerList

protected EventListenerList listenerList
Manages event listeners for this Document.

Constructor Detail

AbstractDocument

protected AbstractDocument(AbstractDocument.Content doc)
Creates a new AbstractDocument with the specified AbstractDocument.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 AbstractDocument.Content model and AbstractDocument.AttributeContext.

Parameters:
doc - the Content model to be used in this Document
ctx - the AttributeContext to use
See Also:
GapContent, StringContent
Method Detail

getParagraphElement

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

Parameters:
pos - the position for which to get the paragraph element
Returns:
the paragraph Element that holds the specified position

getDefaultRootElement

public abstract Element getDefaultRootElement()
Returns the default root 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.

Specified by:
getDefaultRootElement in interface Document
Returns:
the default root Element of this Document

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 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:
AbstractDocument.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 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:
AbstractDocument.LeafElement

createPosition

public Position createPosition(int offset)
                        throws BadLocationException
Creates a Position that keeps track of the location at the specified offset.

Specified by:
createPosition in interface Document
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

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 AbstractDocument.AttributeContext used in this Document.

Returns:
the AbstractDocument.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 AbstractDocument.Content model for this Document

Returns:
the AbstractDocument.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

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 Position which will always mark the end of the Document.

Specified by:
getEndPosition in interface Document
Returns:
a Position which will always mark the end of the Document

getLength

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

Specified by:
getLength in interface Document
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

getProperty

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

Specified by:
getProperty in interface Document
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 getDefaultRootElement(). Document implementations that support multiple roots must override this method and return all roots here.

Specified by:
getRootElements in interface Document
Returns:
all root elements of this Document

getStartPosition

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

Specified by:
getStartPosition in interface Document
Returns:
a Position which will always mark the beginning of the Document

getText

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

Specified by:
getText in interface Document
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)
             throws BadLocationException
Fetches a piece of this Document's content and stores it in the given Segment.

Specified by:
getText in interface Document
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

insertString

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

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

Specified by:
insertString in interface Document
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.

Specified by:
putProperty in interface Document
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)
            throws BadLocationException
Removes a piece of content from this Document.

If a 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 replace(int, int, java.lang.String, javax.swing.text.AttributeSet).

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

Specified by:
remove in interface Document
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

replace

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

If a 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

addDocumentListener

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

Specified by:
addDocumentListener in interface Document
Parameters:
listener - the listener to add

removeDocumentListener

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

Specified by:
removeDocumentListener in interface Document
Parameters:
listener - the listener to remove

getDocumentListeners

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

Returns:
all registered DocumentListeners

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Adds an UndoableEditListener to this Document.

Specified by:
addUndoableEditListener in interface Document
Parameters:
listener - the listener to add

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Removes an UndoableEditListener from this Document.

Specified by:
removeUndoableEditListener in interface Document
Parameters:
listener - the listener to remove

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()
Returns all registered UndoableEditListeners.

Returns:
all registered UndoableEditListeners

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

Specified by:
render in interface Document
Parameters:
runnable - the Runnable to execute

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

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.


getDocumentFilter

public DocumentFilter getDocumentFilter()
Returns the currently installed DocumentFilter for this Document.

Returns:
the currently installed DocumentFilter for this Document
Since:
1.4

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)
Sets the DocumentFilter for this Document.

Parameters:
filter - the DocumentFilter to set
Since:
1.4

dump

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

Parameters:
out - the stream to write the diagnostic information to