java.lang.Objectjavax.swing.text.AbstractDocument
public abstract class AbstractDocument
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 acquired 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 BasicTextUI may be safely updated asynchronously, because all access to the View hierarchy is serialized by BasicTextUI if the document is of type AbstractDocument. The locking assumes that an independant thread will access the View hierarchy only from the DocumentListener methods, and that there will be only one event thread active at a time.
If concurrency support is desired, there are the following additional implications. The code path for any DocumentListener implementation and any UndoListener implementation must be threadsafe, and not access the component lock if trying to be safe from deadlocks. The repaint and revalidate methods on JComponent are safe.
AbstractDocument models an implied break at the end of the document. Among other things this allows you to position the caret after the last character. As a result of this, getLength returns one less than the length of the Content. If you create your own Content, be sure and initialize it to have an additional character. Refer to StringContent and GapContent for examples of this. Another implication of this is that Elements that model the implied end character will have an endOffset == (getLength() + 1). For example, in DefaultStyledDocument getParagraphElement(getLength()).getEndOffset() == getLength() + 1 .
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 applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans TM has been added to the java.beans package. Please see XMLEncoder .
Nested Class Summary | |
---|---|
class |
AbstractDocument.AbstractElement
Implements the abstract part of an element. |
static interface |
AbstractDocument.AttributeContext
An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques. |
class |
AbstractDocument.BranchElement
Implements a composite element that contains other elements. |
static interface |
AbstractDocument.Content
Interface to describe a sequence of character content that can be edited. |
class |
AbstractDocument.DefaultDocumentEvent
Stores document changes as the document is being modified. |
static class |
AbstractDocument.ElementEdit
An implementation of ElementChange that can be added to the document event. |
class |
AbstractDocument.LeafElement
Implements an element that directly represents content of some kind. |
Field Summary | |
---|---|
protected static String |
BAD_LOCATION
Error message to indicate a bad location. |
static String |
BidiElementName
Name of elements used to hold a unidirectional run |
static String |
ContentElementName
Name of elements used to represent content |
static String |
ElementNameAttribute
Name of the attribute used to specify element names. |
protected 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). |
Fields inherited from interface javax.swing.text. Document |
---|
StreamDescriptionProperty , TitleProperty |
Constructor Summary | |
---|---|
protected |
AbstractDocument
(
AbstractDocument.Content
data) Constructs a new AbstractDocument, wrapped around some specified content storage mechanism. |
protected |
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. |
|
protected Element |
createBranchElement
(
Element
parent,
AttributeSet
a) Creates a document branch element, that can contain other elements. |
|
protected 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. |
|
protected void |
fireChangedUpdate
(
DocumentEvent
e) Notifies all listeners that have registered interest for notification on this event type. |
|
protected void |
fireInsertUpdate
(
DocumentEvent
e) Notifies all listeners that have registered interest for notification on this event type. |
|
protected void |
fireRemoveUpdate
(
DocumentEvent
e) Notifies all listeners that have registered interest for notification on this event type. |
|
protected void |
fireUndoableEditUpdate
(
UndoableEditEvent
e) Notifies all listeners that have registered interest for notification on this event type. |
|
int |
getAsynchronousLoadPriority
() Gets the asynchronous loading priority. |
|
protected AbstractDocument.AttributeContext |
getAttributeContext
() Fetches the context for managing attributes. |
|
Element |
getBidiRootElement
() Returns the root element of the bidirectional structure for this document. |
|
protected AbstractDocument.Content |
getContent
() Gets the content for the document. |
|
protected Thread |
getCurrentWriter
() Fetches the current writing thread if there is one. |
|
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. |
|
DocumentFilter |
getDocumentFilter
() Returns the DocumentFilter that is responsible for filtering of insertion/removal. |
|
DocumentListener [] |
getDocumentListeners
() Returns an array of all the document listeners registered on this document. |
|
Dictionary < Object , Object > |
getDocumentProperties
() Supports 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. |
|
|
getListeners
(
Class
<T> listenerType) Returns an array of all the objects currently registered as FooListeners upon this document. |
|
abstract Element |
getParagraphElement
(int pos) Get the paragraph element containing the given position. |
|
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) Fetches the text contained within the given portion of the document. |
|
UndoableEditListener [] |
getUndoableEditListeners
() Returns an array of all the undoable edit listeners registered on this document. |
|
void |
insertString
(int offs,
String
str,
AttributeSet
a) Inserts some content into the document. |
|
protected void |
insertUpdate
(
AbstractDocument.DefaultDocumentEvent
chng,
AttributeSet
attr) Updates document structure as a result of text insertion. |
|
protected void |
postRemoveUpdate
(
AbstractDocument.DefaultDocumentEvent
chng) Updates any document structure as a result of text removal. |
|
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. |
|
protected 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 |
replace
(int offset, int length,
String
text,
AttributeSet
attrs) Deletes the region of text from offset to offset + length, and replaces it with text. |
|
void |
setAsynchronousLoadPriority
(int p) Sets the asynchronous loading priority. |
|
void |
setDocumentFilter
(
DocumentFilter
filter) Sets the DocumentFilter. |
|
void |
setDocumentProperties
(
Dictionary
<
Object
,
Object
> x) Replaces the document properties dictionary for this document. |
|
protected void |
writeLock
() Acquires a lock to begin mutating the document this lock protects. |
|
protected void |
writeUnlock
() Releases a write lock previously obtained via writeLock. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Field Detail |
---|
protected EventListenerList listenerList
protected static final String BAD_LOCATION
public static final String ParagraphElementName
public static final String ContentElementName
public static final String SectionElementName
public static final String BidiElementName
public static final String ElementNameAttribute
Constructor Detail |
---|
protected AbstractDocument(AbstractDocument.Content data)
protected AbstractDocument(AbstractDocument.Content data, AbstractDocument.AttributeContext context)
Method Detail |
---|
public Dictionary<Object,Object> getDocumentProperties()
public void setDocumentProperties(Dictionary<Object,Object> x)
protected void fireInsertUpdate(DocumentEvent e)
protected void fireChangedUpdate(DocumentEvent e)
protected void fireRemoveUpdate(DocumentEvent e)
protected void fireUndoableEditUpdate(UndoableEditEvent e)
public <T extends EventListener> T[] getListeners(Class<T> listenerType)
You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a document d for its document listeners with the following code:
DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));If no such listeners exist, this method returns an empty array.
public int getAsynchronousLoadPriority()
public void setAsynchronousLoadPriority(int p)
public void setDocumentFilter(DocumentFilter filter)
public DocumentFilter getDocumentFilter()
public void render(Runnable r)
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, its 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
How to Use Threads
Threads and Swing
for more information.
public int getLength()
public void addDocumentListener(DocumentListener listener)
public void removeDocumentListener(DocumentListener listener)
public DocumentListener[] getDocumentListeners()
public void addUndoableEditListener(UndoableEditListener listener)
public void removeUndoableEditListener(UndoableEditListener listener)
public UndoableEditListener[] getUndoableEditListeners()
public final Object getProperty(Object key)
getDocumentProperties().get(key);
public final void putProperty(Object key, Object value)
getDocumentProperties().put(key, value);If value is null this method will remove the property.
public void remove(int offs, int len) throws BadLocationException
This method is thread safe, although most Swing methods are not. Please see
How to Use Threads
Threads and Swing
for more information.
public void replace(int offset, int length, String text, AttributeSet attrs) throws BadLocationException
public void insertString(int offs, String str, AttributeSet a) throws BadLocationException
This method is thread safe, although most Swing methods are not. Please see
How to Use Threads
Threads and Swing
for more information.
public String getText(int offset, int length) throws BadLocationException
public void getText(int offset, int length, Segment txt) throws BadLocationException
If the partialReturn property on the txt parameter is false, the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true, only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:
int nleft = doc.getDocumentLength(); Segment text = new Segment(); int offs = 0; text.setPartialReturn(true); while (nleft > 0) { doc.getText(offs, nleft, text); // do something with text nleft -= text.count; offs += text.count; }
public Position createPosition(int offs) throws BadLocationException
This method is thread safe, although most Swing methods are not. Please see
How to Use Threads
Threads and Swing
for more information.
public final Position getStartPosition()
public final Position getEndPosition()
public Element[] getRootElements()
public abstract Element getDefaultRootElement()
public Element getBidiRootElement()
public abstract Element getParagraphElement(int pos)
protected final AbstractDocument.AttributeContext getAttributeContext()
protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
public void dump(PrintStream out)
protected final AbstractDocument.Content getContent()
protected Element createLeafElement(Element parent, AttributeSet a, int p0, int p1)
protected Element createBranchElement(Element parent, AttributeSet a)
protected final Thread getCurrentWriter()
protected final void writeLock()
Calls to writeLock must be balanced with calls to writeUnlock, else the Document will be left in a locked state so that no reading or writing can be done.
protected final void writeUnlock()
public final void readLock()
public final void readUnlock()
readLock(); try { // do something } finally { readUnlock(); }