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

Dictionary
Object> getDocumentProperties()
Returns the properties of this Document.
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.
extends EventListener> T[] getListeners(Class listenerType)
Returns all registered listeners of a given listener type.
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.
Position
getEndPosition()
Returns a Position which will always mark the end of the Document.
int
getLength()
Returns the length of this Document's content.
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 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, extends Object> getClass, finalize, 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:
"document location failure"

BidiElementName

public static final String BidiElementName
Standard name for unidirectional Elements.
Field Value:
"bidi level"

ContentElementName

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

ElementNameAttribute

public static final String ElementNameAttribute
Attribute key for storing the element name.
Field Value:
"$ename"

ParagraphElementName

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

SectionElementName

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

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

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

Method Details

Object> getDocumentProperties

public DictionaryObject> getDocumentProperties()
Returns the properties of this Document.
Returns:
the properties of this Document

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

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

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

extends EventListener> T[] getListeners

public extends EventListener> T[] 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

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

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

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

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

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

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.

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

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.

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

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

AbstractDocument.java -- Copyright (C) 2002, 2004, 2005, 2006 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.