Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.awt.swing.text.AbstractDocument

java.lang.Object
    |
    +----java.awt.swing.text.AbstractDocument
Subclasses:
DefaultStyledDocument, PlainDocument

public abstract class AbstractDocument
extends Object
implements Document, Serializable
An implementation of the document interface to serve as a basis for implementing various kinds of documents. At this level there is very little policy, so there is a corresponding increase in difficulty of use.

This class implements a locking mechanism for the document. It allows multiple readers or one writer, and writers must wait until all observers of the document have been notified of a previous change before beginning another mutation to the document. The read lock is aquired and released using the render method. A write lock is aquired by the methods that mutate the document, and are held for the duration of the method call. Notification is done on the thread that produced the mutation, and the thread has full read access to the document for the duration of the notification, but other readers are kept out until the notification has finished. The notification is a beans event notification which does not allow any further mutations until all listeners have been notified.

Any models subclassed from this class and used in conjunction with a text component that has a look and feel implementation that is derived from DefaultTextUI may be safely updated asynchronously. The rendering in DefaultTextUI occurs under the protection of the render method, which makes rendering safe if it is running on the event thread (which happens if using repaint to schedule updates). The code path for any DocumentListener implementation must not access the component lock if trying to be safe from deadlocks. The repaint and revalidate methods on JComponent are safe.

Warning: serialized objects of this class will not be compatible with future swing releases. The current serialization support is appropriate for short term storage or RMI between Swing1.0 applications. It will not be possible to load serialized Swing1.0 objects with future releases of Swing. The JDK1.2 release of Swing will be the compatibility baseline for the serialized form of Swing objects.


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

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

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

Method Summary
void  addDocumentListener(DocumentListener listener)
Adds a document listener for notification of any changes.
void  addUndoableEditListener(UndoableEditListener listener)
Adds an undo listener for notification of any changes.
Element  createBranchElement(Element parent, AttributeSet a)
Creates a document branch element, that can contain other elements.
Element  createLeafElement(Element parent, AttributeSet a, int p0, int p1)
Creates a document leaf element.
Position  createPosition(int offs)
Returns a position that will track change as the document is altered.
void  dump(PrintStream out)
Gives a diagnostic dump.
void  fireChangedUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
void  fireInsertUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
void  fireRemoveUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
void  fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type.
AbstractDocument.AttributeContext  getAttributeContext()
Fetches the context for managing attributes.
AbstractDocument.Content  getContent()
Gets the content for the document.
Thread  getCurrentWriter()
Fetches the current writing thread if there is one.
Element  getDefaultRootElement()
Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
Dictionary  getDocumentProperties()
Support for managing a set of properties.
Position  getEndPosition()
Returns a position that represents the end of the document.
int  getLength()
Returns the length of the data.
Object  getProperty(Object key)
A convenience method for looking up a property value.
Element[]  getRootElements()
Gets all root elements defined.
Position  getStartPosition()
Returns a position that represents the start of the document.
String  getText(int offset, int length)
Gets a sequence of text from the document.
void  getText(int offset, int length, Segment txt)
Gets some text from the document potentially without making a copy.
void  insertString(int offs, String str, AttributeSet a)
Inserts some content into the document.
void  insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Updates document structure as a result of text insertion.
void  putProperty(Object key, Object value)
A convenience method for storing up a property value.
void  readLock()
Acquires a lock to begin reading some state from the document.
void  readUnlock()
Does a read unlock.
void  remove(int offs, int len)
Removes some content from the document.
void  removeDocumentListener(DocumentListener listener)
Removes a document listener.
void  removeUndoableEditListener(UndoableEditListener listener)
Removes an undo listener.
void  removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal.
void  render(Runnable r)
This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.
void  setDocumentProperties(Dictionary x)
Replace the document properties dictionary for this document.
void  writeLock()
Acquires a lock to begin mutating the document this lock protects.
void  writeUnlock()
Releases the write lock held because the write operation is finished.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

listenerList

protected EventListenerList listenerList
The event listener list for the document.

BAD_LOCATION

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

ParagraphElementName

public static final String ParagraphElementName
Name of elements used to represent paragraphs

ContentElementName

public static final String ContentElementName
Name of elements used to represent content

SectionElementName

public static final String SectionElementName
Name of elements used to hold sections (lines/paragraphs).

ElementNameAttribute

public static final String ElementNameAttribute
Name of the attribute used to specify element names.
Constructor Detail

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
Parameters:
data - the content

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data,
                           AbstractDocument.AttributeContext context)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
Parameters:
data - the content
Method Detail

getDocumentProperties

public Dictionary getDocumentProperties()
Support for managing a set of properties. Callers can use the documentProperties dictionary to annotate the document with document-wide properties.
Returns:
a non null Dictionary
See Also:
setDocumentProperties

setDocumentProperties

public void setDocumentProperties(Dictionary x)
Replace the document properties dictionary for this document.
See Also:
getDocumentProperties

fireInsertUpdate

protected void fireInsertUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.
Parameters:
e - the event
See Also:
EventListenerList

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.
Parameters:
e - the event
See Also:
EventListenerList

fireRemoveUpdate

protected void fireRemoveUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.
Parameters:
e - the event
See Also:
EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.
Parameters:
e - the event
See Also:
EventListenerList

render

public void render(Runnable r)
This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

This is implemented to aquire a read lock for the duration of the runnables execution. There may be multiple runnables executing at the same time, and all writers will be blocked while there are active rendering runnables. If the runnable throws an exception, it's lock will be safely released. There is no protection against a runnable that never exits, which will effectively leave the document locked for it's lifetime.

If the given runnable attempts to make any mutations in this implementation, a deadlock will occur. There is no tracking of individual rendering threads to enable detecting this situation, but a subclass could incur the overhead of tracking them and throwing an error.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Implements:
render in interface Document
Parameters:
r - the renderer to execute.

getLength

public int getLength()
Returns the length of the data. This is the number of characters of content that represents the users data.
Implements:
getLength in interface Document
Returns:
the length
See Also:
getLength

addDocumentListener

public void addDocumentListener(DocumentListener listener)
Adds a document listener for notification of any changes.
Implements:
addDocumentListener in interface Document
Parameters:
listener - the listener
See Also:
addDocumentListener

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)
Removes a document listener.
Implements:
removeDocumentListener in interface Document
Parameters:
listener - the listener
See Also:
removeDocumentListener

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Adds an undo listener for notification of any changes. Undo/Redo operations performed on the UndoableEdit will cause the appropriate DocumentEvent to be fired to keep the view(s) in sync with the model.
Implements:
addUndoableEditListener in interface Document
Parameters:
listener - the listener
See Also:
addUndoableEditListener

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Removes an undo listener.
Implements:
removeUndoableEditListener in interface Document
Parameters:
listener - the listener
See Also:
removeDocumentListener

getProperty

public final Object getProperty(Object key)
A convenience method for looking up a property value. It is equivalent to:
 getDocumentProperties().get(key);
 
Implements:
getProperty in interface Document
Returns:
the value of this property or null
See Also:
getDocumentProperties

putProperty

public final void putProperty(Object key,
                              Object value)
A convenience method for storing up a property value. It is equivalent to:
 getDocumentProperties().put(key, value);
 
If value is null this method will remove the property
Implements:
putProperty in interface Document
See Also:
getDocumentProperties

remove

public void remove(int offs,
                   int len) throws BadLocationException
Removes some content from the document. Removing content causes a write lock to be held while the actual changes are taking place. Observers are notified of the change on the thread that called this method.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Implements:
remove in interface Document
Parameters:
offs - the starting offset
len - the number of characters to remove
Throws:
BadLocationException - the given remove position is not a valid position within the document
See Also:
remove

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a) throws BadLocationException
Inserts some content into the document. Inserting content causes a write lock to be held while the actual changes are taking place, followed by notification to the observers on the thread that grabbed the write lock.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Implements:
insertString in interface Document
Parameters:
offs - the starting offset
str - the string to insert
a - the attributes for the inserted content
Throws:
BadLocationException - the given insert position is not a valid position within the document
See Also:
insertString

getText

public String getText(int offset,
                      int length) throws BadLocationException
Gets a sequence of text from the document.
Implements:
getText in interface Document
Parameters:
offset - the starting offset
length - the number of characters to retrieve
Returns:
the text
Throws:
BadLocationException - the range given includes a position that is not a valid position within the document
See Also:
getText

getText

public void getText(int offset,
                    int length,
                    Segment txt) throws BadLocationException
Gets some text from the document potentially without making a copy. The character array returned in the given Segment should never be mutated. This kind of access to the characters of the document is provided to help make the rendering potentially more efficient. The caller should make no assumptions about the lifetime of the returned character array, which should be copied if needed beyond the use for rendering.
Implements:
getText in interface Document
Parameters:
offset - the starting offset
length - the number of characters to retrieve
txt - the Segment object to retrieve the text into
Throws:
BadLocationException - the range given includes a position that is not a valid position within the document

createPosition

public Position createPosition(int offs) throws BadLocationException
Returns a position that will track change as the document is altered.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Implements:
createPosition in interface Document
Parameters:
offs - the position
Returns:
the position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
createPosition

getStartPosition

public final Position getStartPosition()
Returns a position that represents the start of the document. The position returned can be counted on to track change and stay located at the beginning of the document.
Implements:
getStartPosition in interface Document
Returns:
the position

getEndPosition

public final Position getEndPosition()
Returns a position that represents the end of the document. The position returned can be counted on to track change and stay located at the end of the document.
Implements:
getEndPosition in interface Document
Returns:
the position

getRootElements

public Element[] getRootElements()
Gets all root elements defined. Typically, there will only be one so the default implementation is to return the default root element.
Implements:
getRootElements in interface Document
Returns:
the root element

getDefaultRootElement

public abstract Element getDefaultRootElement()
Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
Implements:
getDefaultRootElement in interface Document
Returns:
the root element
See Also:
getDefaultRootElement

getAttributeContext

protected final AbstractDocument.AttributeContext getAttributeContext()
Fetches the context for managing attributes. This method effectively establishes the strategy used for compressing AttributeSet information.
Returns:
the context

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. If a subclass of this class reimplements this method, it should delegate to the superclass as well.
Parameters:
chng - a description of the change
attr - the attributes for the change

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal. This will happen within a write lock. If a subclass of this class reimplements this method, it should delegate to the superclass as well.
Parameters:
chng - a description of the change

dump

public void dump(PrintStream out)
Gives a diagnostic dump.
Parameters:
out - the output stream

getContent

protected final AbstractDocument.Content getContent()
Gets the content for the document.
Returns:
the content

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)
Creates a document leaf element. Hook through which elements are created to represent the document structure. Because this implementation keeps structure and content seperate, elements grow automatically when content is extended so splits of existing elements follow. The document itself gets to decide how to generate elements to give flexibility in the type of elements used.
Parameters:
parent - the parent element
a - the attributes for the element
p0 - the beginning of the range
p1 - the end of the range
Returns:
the new element

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)
Creates a document branch element, that can contain other elements.
Parameters:
parent - the parent element
a - the attributes
Returns:
the element

getCurrentWriter

protected final Thread getCurrentWriter()
Fetches the current writing thread if there is one. This can be used to distinguish whether a method is being called as part of an existing modification or if a lock needs to be acquired and a new transaction started.

writeLock

protected final void writeLock()
Acquires a lock to begin mutating the document this lock protects. There can be no notification of changes or reading going on in order to gain the lock.

writeUnlock

protected final void writeUnlock()
Releases the write lock held because the write operation is finished. This allows either a new writer or readers to aquire a lock.

readLock

protected final void readLock()
Acquires a lock to begin reading some state from the document. There can be multiple readers at the same time and reading can occur while notification to the listeners is going on, but writing blocks the readers.

readUnlock

protected final void readUnlock()
Does a read unlock. One of the readers is done. If there are no more readers then writing can begin again.

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.