javax.swing.text

Class AbstractDocument

Implemented Interfaces:
Document, Serializable
Known Direct 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

abstract 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.
static String
ParagraphElementName
Standard name for paragraph Elements.
static String
SectionElementName
Standard name for section Elements.
protected EventListenerList
listenerList
Manages event listeners for this Document.

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Constructor Summary

AbstractDocument(AbstractDocument.Content doc)
Creates a new AbstractDocument with the specified AbstractDocument.Content model.
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.
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
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.
EventListener[]
getListeners(Class listenerType)
Returns all registered listeners of a given listener type.
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 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 Details

BAD_LOCATION

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

Field Value:
""


BidiElementName

public static final String BidiElementName
Standard name for unidirectional Elements.

Field Value:
""


ContentElementName

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

Field Value:
""


ElementNameAttribute

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

Field Value:
""


ParagraphElementName

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

Field Value:
""


SectionElementName

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

Field Value:
""


listenerList

protected EventListenerList listenerList
Manages event listeners for this Document.

Constructor Details

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 Details

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


addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Adds an UndoableEditListener to this Document.
Specified by:
addUndoableEditListener in interface 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 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


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


getDocumentFilter

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

Returns:
the currently installed DocumentFilter for this Document

Since:
1.4


getDocumentListeners

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

Returns:
all registered DocumentListeners


getDocumentProperties

public Dictionary getDocumentProperties()
Returns the properties of this Document.

Returns:
the properties of this Document


getEndPosition

public 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 EventListener[] getListeners(Class 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 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


getProperty

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


getUndoableEditListeners

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

Returns:
all registered UndoableEditListeners


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.
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 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 void readLock()
Blocks until a read lock can be obtained. Must block if there is currently a writer modifying the Document.


readUnlock

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


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


removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Removes an UndoableEditListener from this Document.
Specified by:
removeUndoableEditListener in interface 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 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


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.

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 DocumentFilter for this Document.

Parameters:
filter - the DocumentFilter to set

Since:
1.4


setDocumentProperties

public void setDocumentProperties(Dictionary p)
Sets the properties of this Document.

Parameters:
p - the document properties to set


writeLock

protected 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 void writeUnlock()
Releases the write lock. This allows waiting readers or writers to obtain the lock.


AbstractDocument.java -- Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.