javax.swing.text
Class AbstractDocument

java.lang.Object
  javax.swing.text.AbstractDocument

All Implemented Interfaces:

Document, Serializable

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

Author:

Timothy Prinzing

See Also:

Serialized Form

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.
(package private) class	AbstractDocument.BidiElement Represents an element of the bidirectional element structure.
(package private) class	AbstractDocument.BidiRootElement Represents the root element of the bidirectional element structure.
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.
private class	AbstractDocument.DefaultFilterBypass
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

(package private) static String	AsyncLoadPriority Document property that indicates asynchronous loading is desired, with the thread priority given as the value.
protected static String	BAD_LOCATION Error message to indicate a bad location.
private static String	BAD_LOCK_STATE
static String	BidiElementName Name of elements used to hold a unidirectional run
private AbstractDocument.BranchElement	bidiRoot The root of the bidirectional structure for this document.
static String	ContentElementName Name of elements used to represent content
private AbstractDocument.AttributeContext	context Factory for the attributes.
private Thread	currWriter
private AbstractDocument.Content	data Where the text is actually stored, and a set of marks that track change as the document is edited are managed.
private static Boolean	defaultI18NProperty
private DocumentFilter	documentFilter Filter for inserting/removing of text.
private Dictionary	documentProperties Storage for document-wide properties.
static String	ElementNameAttribute Name of the attribute used to specify element names.
private DocumentFilter.FilterBypass	filterBypass Used by DocumentFilter to do actual insert/remove.
(package private) static String	I18NProperty Document property that indicates whether internationalization functions such as text reordering or reshaping should be performed.
protected EventListenerList	listenerList The event listener list for the document.
(package private) static Object	MultiByteProperty Document property that indicates if a character has been inserted into the document that is more than one byte long.
private boolean	notifyingListeners True will notifying listeners.
private int	numReaders
private int	numWriters The number of writers, all obtained from currWriter.
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.
private byte[]	calculateBidiLevels(int firstPStart, int lastPEnd) Calculate the levels array for a range of paragraphs.
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	getDocumentProperties() Supports managing a set of properties.
Position	getEndPosition() Returns a position that represents the end of the document.
private DocumentFilter.FilterBypass	getFilterBypass() Returns the FilterBypass.
int	getLength() Returns the length of the data.
EventListener[]	getListeners(Class 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.
(package private) void	handleInsertString(int offs, String str, AttributeSet a) Performs the actual work of inserting the text; it is assumed the caller has obtained a write lock before invoking this.
(package private) void	handleRemove(int offs, int len) Performs the actual work of the remove.
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.
private static boolean	isComplex(char ch)
private static boolean	isComplex(char[] text, int start, int limit)
(package private) boolean	isLeftToRight(int p0, int p1) Returns true if the text in the range p0 to p1 is left to right.
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.
private void	readObject(ObjectInputStream s)
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 x) Replaces the document properties dictionary for this document.
(package private) void	updateBidi(AbstractDocument.DefaultDocumentEvent chng) Update the bidi element structure as a result of the given change to the 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

numReaders

private transient int numReaders

currWriter

private transient Thread currWriter

numWriters

private transient int numWriters

The number of writers, all obtained from currWriter.

notifyingListeners

private transient boolean notifyingListeners

True will notifying listeners.

defaultI18NProperty

private static Boolean defaultI18NProperty

documentProperties

private Dictionary documentProperties

Storage for document-wide properties.

listenerList

protected EventListenerList listenerList

The event listener list for the document.

data

private AbstractDocument.Content data

Where the text is actually stored, and a set of marks that track change as the document is edited are managed.

context

private AbstractDocument.AttributeContext context

Factory for the attributes. This is the strategy for attribute compression and control of the lifetime of a set of attributes as a collection. This may be shared with other documents.

bidiRoot

private transient AbstractDocument.BranchElement bidiRoot

The root of the bidirectional structure for this document. Its children represent character runs with the same Unicode bidi level.

documentFilter

private DocumentFilter documentFilter

Filter for inserting/removing of text.

filterBypass

private transient DocumentFilter.FilterBypass filterBypass

Used by DocumentFilter to do actual insert/remove.

BAD_LOCK_STATE

private static final String BAD_LOCK_STATE

See Also:

Constant Field Values

BAD_LOCATION

protected static final String BAD_LOCATION

Error message to indicate a bad location.

See Also:

Constant Field Values

ParagraphElementName

public static final String ParagraphElementName

Name of elements used to represent paragraphs

See Also:

Constant Field Values

ContentElementName

public static final String ContentElementName

Name of elements used to represent content

See Also:

Constant Field Values

SectionElementName

public static final String SectionElementName

Name of elements used to hold sections (lines/paragraphs).

See Also:

Constant Field Values

BidiElementName

public static final String BidiElementName

Name of elements used to hold a unidirectional run

See Also:

Constant Field Values

ElementNameAttribute

public static final String ElementNameAttribute

Name of the attribute used to specify element names.

See Also:

Constant Field Values

I18NProperty

static final String I18NProperty

Document property that indicates whether internationalization functions such as text reordering or reshaping should be performed. This property should not be publicly exposed, since it is used for implementation convenience only. As a side effect, copies of this property may be in its subclasses that live in different packages (e.g. HTMLDocument as of now), so those copies should also be taken care of when this property needs to be modified.

See Also:

Constant Field Values

MultiByteProperty

static final Object MultiByteProperty

Document property that indicates if a character has been inserted into the document that is more than one byte long. GlyphView uses this to determine if it should use BreakIterator.

AsyncLoadPriority

static final String AsyncLoadPriority

Document property that indicates asynchronous loading is desired, with the thread priority given as the value.

See Also:

Constant Field Values

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

context - the attribute context

Method Detail

getDocumentProperties

public Dictionary getDocumentProperties()

Supports 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(java.util.Dictionary)

setDocumentProperties

public void setDocumentProperties(Dictionary x)

Replaces the document properties dictionary for this document.

Parameters:

x - the new dictionary

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

getListeners

public EventListener[] getListeners(Class listenerType)

Returns an array of all the objects currently registered as FooListeners upon this document. FooListeners are registered using the addFooListener method.

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.

Parameters:

listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener

Returns:

an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added

Throws:

ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener

Since:

1.3

See Also:

getDocumentListeners(), getUndoableEditListeners()

getAsynchronousLoadPriority

public int getAsynchronousLoadPriority()

Gets the asynchronous loading priority. If less than zero, the document should not be loaded asynchronously.

Returns:

the asynchronous loading priority, or -1 if the document should not be loaded asynchronously

setAsynchronousLoadPriority

public void setAsynchronousLoadPriority(int p)

Sets the asynchronous loading priority.

Parameters:

p - the new asynchronous loading priority; a value less than zero indicates that the document should not be loaded asynchronously

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)

Sets the DocumentFilter. The DocumentFilter is passed insert and remove to conditionally allow inserting/deleting of the text. A null value indicates that no filtering will occur.

Parameters:

filter - the DocumentFilter used to constrain text

Since:

1.4

See Also:

getDocumentFilter()

getDocumentFilter

public DocumentFilter getDocumentFilter()

Returns the DocumentFilter that is responsible for filtering of insertion/removal. A null return value implies no filtering is to occur.

Returns:

the DocumentFilter

Since:

1.4

See Also:

setDocumentFilter(javax.swing.text.DocumentFilter)

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, 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 Threads and Swing for more information.

Specified by:

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.

Specified by:

getLength in interface Document

Returns:

the length >= 0

See Also:

Document.getLength()

addDocumentListener

public void addDocumentListener(DocumentListener listener)

Adds a document listener for notification of any changes.

Specified by:

addDocumentListener in interface Document

Parameters:

listener - the DocumentListener to add

See Also:

Document.addDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)

Removes a document listener.

Specified by:

removeDocumentListener in interface Document

Parameters:

listener - the DocumentListener to remove

See Also:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

getDocumentListeners

public DocumentListener[] getDocumentListeners()

Returns an array of all the document listeners registered on this document.

Returns:

all of this document's DocumentListeners or an empty array if no document listeners are currently registered

Since:

1.4

See Also:

addDocumentListener(javax.swing.event.DocumentListener), removeDocumentListener(javax.swing.event.DocumentListener)

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.

Specified by:

addUndoableEditListener in interface Document

Parameters:

listener - the UndoableEditListener to add

See Also:

Document.addUndoableEditListener(javax.swing.event.UndoableEditListener)

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)

Removes an undo listener.

Specified by:

removeUndoableEditListener in interface Document

Parameters:

listener - the UndoableEditListener to remove

See Also:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()

Returns an array of all the undoable edit listeners registered on this document.

Returns:

all of this document's UndoableEditListeners or an empty array if no undoable edit listeners are currently registered

Since:

1.4

See Also:

addUndoableEditListener(javax.swing.event.UndoableEditListener), removeUndoableEditListener(javax.swing.event.UndoableEditListener)

getProperty

public final Object getProperty(Object key)

A convenience method for looking up a property value. It is equivalent to:

 getDocumentProperties().get(key);
 

Specified by:

getProperty in interface Document

Parameters:

key - the non-null property key

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.

Specified by:

putProperty in interface Document

Parameters:

key - the non-null key

value - the property value

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.

Specified by:

remove in interface Document

Parameters:

offs - the starting offset >= 0

len - the number of characters to remove >= 0

Throws:

BadLocationException - the given remove position is not a valid position within the document

See Also:

Document.remove(int, int)

handleRemove

void handleRemove(int offs,
                  int len)
            throws BadLocationException

Performs the actual work of the remove. It is assumed the caller will have obtained a writeLock before invoking this.

Throws:

BadLocationException

isComplex

private static final boolean isComplex(char ch)

isComplex

private static final boolean isComplex(char[] text,
                                       int start,
                                       int limit)

replace

public void replace(int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException

Deletes the region of text from offset to offset + length, and replaces it with text. It is up to the implementation as to how this is implemented, some implementations may treat this as two distinct operations: a remove followed by an insert, others may treat the replace as one atomic operation.

Parameters:

offset - index of child element

length - length of text to delete, may be 0 indicating don't delete anything

text - text to insert, null indicates no text to insert

attrs - AttributeSet indicating attributes of inserted text, null is legal, and typically treated as an empty attributeset, but exact interpretation is left to the subclass

Throws:

BadLocationException - the given position is not a valid position within the document

Since:

1.4

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.

Specified by:

insertString in interface Document

Parameters:

offs - the starting offset >= 0

str - the string to insert; does nothing with null/empty strings

a - the attributes for the inserted content

Throws:

BadLocationException - the given insert position is not a valid position within the document

See Also:

Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

handleInsertString

void handleInsertString(int offs,
                        String str,
                        AttributeSet a)
                  throws BadLocationException

Performs the actual work of inserting the text; it is assumed the caller has obtained a write lock before invoking this.

Throws:

BadLocationException

getText

public String getText(int offset,
                      int length)
               throws BadLocationException

Gets a sequence of text from the document.

Specified by:

getText in interface Document

Parameters:

offset - the starting offset >= 0

length - the number of characters to retrieve >= 0

Returns:

the text

Throws:

BadLocationException - the range given includes a position that is not a valid position within the document

See Also:

Document.getText(int, int)

getText

public void getText(int offset,
                    int length,
                    Segment txt)
             throws BadLocationException

Fetches the text contained within the given portion of the document.

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

Specified by:

getText in interface Document

Parameters:

offset - the starting offset >= 0

length - the number of characters to retrieve >= 0

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.

Specified by:

createPosition in interface Document

Parameters:

offs - the position in the model >= 0

Returns:

the position

Throws:

BadLocationException - if the given position does not represent a valid location in the associated document

See Also:

Document.createPosition(int)

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.

Specified by:

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.

Specified by:

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.

Specified by:

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.

Specified by:

getDefaultRootElement in interface Document

Returns:

the root element

See Also:

Document.getDefaultRootElement()

getFilterBypass

private DocumentFilter.FilterBypass getFilterBypass()

Returns the FilterBypass. This will create one if one does not yet exist.

getBidiRootElement

public Element getBidiRootElement()

Returns the root element of the bidirectional structure for this document. Its children represent character runs with a given Unicode bidi level.

isLeftToRight

boolean isLeftToRight(int p0,
                      int p1)

Returns true if the text in the range p0 to p1 is left to right.

getParagraphElement

public abstract Element getParagraphElement(int pos)

Get the paragraph element containing the given position. Sub-classes must define for themselves what exactly constitutes a paragraph. They should keep in mind however that a paragraph should at least be the unit of text over which to run the Unicode bidirectional algorithm.

Parameters:

pos - the starting offset >= 0

Returns:

the element

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 method is called before the text is actually removed from the Content. 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

postRemoveUpdate

protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)

Updates any document structure as a result of text removal. This method is called after the text has been removed from the Content. 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

updateBidi

void updateBidi(AbstractDocument.DefaultDocumentEvent chng)

Update the bidi element structure as a result of the given change to the document. The given change will be updated to reflect the changes made to the bidi structure. This method assumes that every offset in the model is contained in exactly one paragraph. This method also assumes that it is called after the change is made to the default element structure.

calculateBidiLevels

private byte[] calculateBidiLevels(int firstPStart,
                                   int lastPEnd)

Calculate the levels array for a range of paragraphs.

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 separate, 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 >= 0

p1 - the end of the range >= p0

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.

Returns:

the thread actively modifying the document or null if there are no modifications in progress

writeLock

protected final void writeLock()

Acquires a lock to begin mutating the document this lock protects. There can be no writing, notification of changes, or reading going on in order to gain the lock. Additionally a thread is allowed to gain more than one writeLock, as long as it doesn't attempt to gain additional writeLocks from within document notification. Attempting to gain a writeLock from within a DocumentListener notification will result in an IllegalStateException. The ability to obtain more than one writeLock per thread allows subclasses to gain a writeLock, perform a number of operations, then release the lock.

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.

Throws:

IllegalStateException - thrown on illegal lock attempt. If the document is implemented properly, this can only happen if a document listener attempts to mutate the document. This situation violates the bean event model where order of delivery is not guaranteed and all listeners should be notified before further mutations are allowed.

writeUnlock

protected final void writeUnlock()

Releases a write lock previously obtained via writeLock. After decrementing the lock count if there are no oustanding locks this will allow a new writer, or readers.

See Also:

writeLock()

readLock

public final void readLock()

Acquires a lock to begin reading some state from the document. There can be multiple readers at the same time. Writing blocks the readers until notification of the change to the listeners has been completed. This method should be used very carefully to avoid unintended compromise of the document. It should always be balanced with a readUnlock.

See Also:

readUnlock()

readUnlock

public final void readUnlock()

Does a read unlock. This signals that one of the readers is done. If there are no more readers then writing can begin again. This should be balanced with a readLock, and should occur in a finally statement so that the balance is guaranteed. The following is an example.

     readLock();
     try {
         // do something
     } finally {
         readUnlock();
     }
 

See Also:

readLock()

readObject

private void readObject(ObjectInputStream s)
                 throws ClassNotFoundException,
                        IOException

Throws:

ClassNotFoundException

IOException