oracle.javatools.editor
Class BasicDocument

java.lang.Object
  oracle.javatools.editor.BasicDocument

All Implemented Interfaces:

java.beans.PropertyChangeListener, java.util.EventListener, javax.swing.text.Document, TextBufferListener

public class BasicDocument
extends java.lang.Object
implements javax.swing.text.Document, TextBufferListener, java.beans.PropertyChangeListener

A BasicDocument is an implementation of the Document interface, similar to "PlainDocument" without the extra overhead of the Element structures for maintaining line number information, and with a different text buffer implementation. This document does not maintain any attribute information currently.

Each BasicDocument instance has an associated LanguageSupport that adds extra document support specific to a given document language, such as Java or HTML. The LanguageSupport for a document is set up using the provided filename through suffix mapping, or by explicitly setting the LanguageSupport by calling setLanguageSupport() with a LanguageSupport instance.

Like the Swing text document implementations, this document implementation provides support for UndoableEdit's. The document relies on the underlying TextBuffer for generating the UndoableEdit's. Note that UndoableEdit's are fired by this document only for edits initiated through this document. Edits performed on the TextBuffer directly apart from this document will not result in an UndoableEdit through this document.

Note that the compound edit support here in BasicDocument has been deprecated. Clients should use the edit support in BasicEditorPane instead, which also includes support for specifying an edit name (for display) and for saving caret position information with the UndoableEdit. Please refer for information regarding undo support.

Lastly, please note that this document implementation currently does not support composed or bidi text input due to the model changes to optimize memory use and performance. This is an open issue that will be addressed soon.

See Also:

LanguageSupport

Nested Class Summary

static interface

BasicDocument.PrePostDocumentListener The PrePostDocumentListener is a listener interface that allows secondary models (such as a DocumentRenderer or CodeFoldingModel) to be notified before and/or after regular document notification.

Field Summary

static java.lang.String	eolTypePropertyName public constant for the eol type property name.
static java.lang.String	readOnlyPropertyName Public constant for the read only property name.

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Fields inherited from interface oracle.javatools.buffer.TextBufferListener

EOL_TYPE_ATTRIBUTE, MODIFIED_ATTRIBUTE, READ_ONLY_ATTRIBUTE, RELOAD_END_ATTRIBUTE, RELOAD_START_ATTRIBUTE

Constructor Summary

BasicDocument()
Create a new default BasicDocument.

BasicDocument(java.lang.String fileName)
Creates a plain text document - this uses the the default TextBuffer implementation as the underlying data model.

BasicDocument(java.lang.String fileName, TextBuffer buffer)
Creates a plain text document using the buffer provider specified.

BasicDocument(TextBuffer buffer)
Create a new BasicDocument using the provided buffer.

Method Summary

void	addDocumentListener(javax.swing.event.DocumentListener listener) Registers the given listener to begin receiving notifications when changes are made to the document.
void	addPrePostDocumentListener(BasicDocument.PrePostDocumentListener listener) Registers the given listener to begin receiving pre/post notifications.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a PropertyChangeListener to the listener list.
void	addUndoableEditListener(javax.swing.event.UndoableEditListener listener) Registers the given listener to begin receiving notifications when undoable edits are made to the document.
void	attributeUpdate(TextBuffer buffer, int attribute) Provides notification regarding a change to one of the buffer attributes.
void	beginEdit() Deprecated. all edits (compound or otherwise) made to the document related to an editor pane should be initiated through BasicEditorPane.beginEdit()
javax.swing.text.Position	createPosition(int offset) This method allows an application to mark a place in a sequence of character content.
void	endEdit() Deprecated. all edits (compound or otherwise) made to the document related to an editor pane should be ended through BasicEditorPane.endEdit()
void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue) Report a bound property update to any registered listeners.
protected void	fireUndoableEditEvent(javax.swing.undo.UndoableEdit edit) An internal utility routine to fire UndoableEdit events that are generated by this document to the undoable edit listeners.
protected NumberRange	getComposedTextRange() Fetch the current range of composed text input - this is generally uncommitted text.
javax.swing.text.Element	getDefaultRootElement() Fetches the default root element for this document.
DocumentRenderer	getDocumentRenderer() Fetches the document renderer from the language support for this document.
javax.swing.text.Position	getEndPosition() Returns a position that represents the end of the document.
LanguageSupport	getLanguageSupport() Fetches the LanguageSupport associated with this document.
int	getLength() Returns number of characters of data currently in the document.
int	getLineCount() Fetches the number of lines in this TextBuffer.
int	getLineEndOffset(int line) Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.
int	getLineFromOffset(int offset) Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias.
LineMap	getLineMap() Fetches a line map for this document for calculating line positions.
int	getLineStartOffset(int line) Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.
javax.swing.text.Element	getParagraphElement(int pos) Get the paragraph element containing the given position.
java.lang.Object	getProperty(java.lang.Object key) Gets properties associated with the document.
javax.swing.text.Element[]	getRootElements() Returns all of the root elements that are defined.
javax.swing.text.Position	getStartPosition() Returns a position that represents the start of the document.
java.lang.String	getText(int offset, int length) Fetches the text contained within the given portion of the document.
void	getText(int offset, int length, javax.swing.text.Segment txt) Fetches the text contained within the given portion of the document.
TextBuffer	getTextBuffer() Fetches the underlying Content of this document.
void	insertString(int offset, java.lang.String str, javax.swing.text.AttributeSet set) Inserts a string into the document.
void	insertUpdate(TextBuffer buffer, int offset, int count, char[] insertedData) Provides notification about an insertion into the text buffer.
void	propertyChange(java.beans.PropertyChangeEvent event) This method gets called when a bound property is changed.
void	putProperty(java.lang.Object key, java.lang.Object value) Puts a new property on the list.
void	readLock() Attempts to acquire a read lock on this document and the underlying text buffer - this is a blocking call.
void	readUnlock() Releases a held read lock on this Document.
void	remove(int offset, int length) Removes a portion of the content of the document.
void	removeDocumentListener(javax.swing.event.DocumentListener listener) Unregisters the given listener from the notification list so it will no longer receive change updates.
void	removePrePostDocumentListener(BasicDocument.PrePostDocumentListener listener) Unregisters the given listener from receiving pre/post notifications.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener from the listener list.
void	removeUndoableEditListener(javax.swing.event.UndoableEditListener listener) Unregisters the given listener from the notification list so it will no longer receive updates.
void	removeUpdate(TextBuffer buffer, int offset, int count, char[] removedData) Provides notification about a removal from the text buffer.
void	render(java.lang.Runnable r) This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.
void	setLanguageSupport(LanguageSupport support) Set the LanguageSupport used by this document to the specified one.
void	setLanguageSupport(java.lang.String fileName) Sets the LanguageSupport for editing the type of content indicated by the specified filename.
void	writeLock() Attempts to acquire a write lock on this document and the underlying text buffer - this is a blocking call.
void	writeLock(boolean checkIfReadOnly) Attempts to acquire a write lock on this document and the underlying text buffer - this is a blocking call.
void	writeUnlock() Releases a held write lock on this Document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

readOnlyPropertyName

public static final java.lang.String readOnlyPropertyName

Public constant for the read only property name.

See Also:

Constant Field Values

eolTypePropertyName

public static final java.lang.String eolTypePropertyName

public constant for the eol type property name.

See Also:

Constant Field Values

Constructor Detail

BasicDocument

public BasicDocument()

Create a new default BasicDocument.

BasicDocument

public BasicDocument(java.lang.String fileName)

Creates a plain text document - this uses the the default TextBuffer implementation as the underlying data model.

Parameters:

fileName - the file name to use when creating a language support

BasicDocument

public BasicDocument(java.lang.String fileName,
                     TextBuffer buffer)

Creates a plain text document using the buffer provider specified.

Parameters:

fileName - the file name to use when creating a language support

buffer - the text bufer to use as the document model

BasicDocument

public BasicDocument(TextBuffer buffer)

Create a new BasicDocument using the provided buffer.

Parameters:

buffer - the text buffer to use as the document model

Method Detail

getComposedTextRange

protected NumberRange getComposedTextRange()

Fetch the current range of composed text input - this is generally uncommitted text. This allows editor view renderers to paint the composed text with a visual indication that it is composed text.

Returns:

a number range for the composed text range, if there is composed text

getTextBuffer

public TextBuffer getTextBuffer()

Fetches the underlying Content of this document.

Returns:

the content

setLanguageSupport

public void setLanguageSupport(java.lang.String fileName)

Sets the LanguageSupport for editing the type of content indicated by the specified filename.

Parameters:

fileName - the name of the file

setLanguageSupport

public void setLanguageSupport(LanguageSupport support)

Set the LanguageSupport used by this document to the specified one.

Parameters:

support - the LanguageSupport to use

getLanguageSupport

public LanguageSupport getLanguageSupport()

Fetches the LanguageSupport associated with this document.

Returns:

the LanguageSupport

getDocumentRenderer

public DocumentRenderer getDocumentRenderer()

Fetches the document renderer from the language support for this document.

Returns:

the DocumentRenderer

beginEdit

public void beginEdit()

Deprecated. all edits (compound or otherwise) made to the document related to an editor pane should be initiated through BasicEditorPane.beginEdit()

Used to instruct the document that it should begin a compound edit that should be fired as one single undoable edit. This relies on the UndoableEdit support of the underlying TextBuffer. If the edit involves a BasicEditorPane instance, use BasicEditorPane.beginEdit() instead so that caret information can also be preserved.

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit()

endEdit

public void endEdit()

Deprecated. all edits (compound or otherwise) made to the document related to an editor pane should be ended through BasicEditorPane.endEdit()

Used to instruct the document that it should end an in progress compound edit and fire a single UndoableEdit representing all the (compound) changes made. This relies on the UndoableEdit support of the underlying TextBuffer.

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit()

readLock

public void readLock()

Attempts to acquire a read lock on this document and the underlying text buffer - this is a blocking call. Note that a call to readLock() must be matched by a call to readUnlock() even if nested within a writeLock()/writeUnlock(). This is to help guarantee correctness.

See Also:

ReadTextBuffer.readLock(), TextBuffer.writeLock()

readUnlock

public void readUnlock()

Releases a held read lock on this Document.

writeLock

public void writeLock()

Attempts to acquire a write lock on this document and the underlying text buffer - this is a blocking call. Note that a call to writeLock() must be matched by a call to writeUnlock().

Throws:

ReadOnlyException - if the buffer is in read only mode.

See Also:

ReadTextBuffer.readLock(), TextBuffer.writeLock()

writeLock

public void writeLock(boolean checkIfReadOnly)

Attempts to acquire a write lock on this document and the underlying text buffer - this is a blocking call. Note that a call to writeLock() must be matched by a call to writeUnlock(). This version of the writeLock() method takes a boolean parameter that controls whether or not an exception is thrown if you attempt to acquire a write lock on a read only text buffer. Note that in most cases, clients should pass true (or use the writeLock() method that takes no arguments) so that they are immediately notified that write operations will fail.

Throws:

ReadOnlyException - if the buffer is in read only mode and checkIfReadOnly is true

See Also:

ReadTextBuffer.readLock(), TextBuffer.writeLock()

writeUnlock

public void writeUnlock()

Releases a held write lock on this Document.

getLineCount

public int getLineCount()

Fetches the number of lines in this TextBuffer. For example, a 5-line TextBuffer has lines 0 through 4.

Returns:

number of lines in TextBuffer

getLineFromOffset

public int getLineFromOffset(int offset)

Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias. This means if line A starts with offset B, and previous line A-1 ends with offset B, getLineFromOffset(B) will return line A.

Returns:

the line containing an offset

getLineStartOffset

public int getLineStartOffset(int line)

Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.

Parameters:

line - a line in the TextBuffer

Returns:

the starting offset of the specified line

getLineEndOffset

public int getLineEndOffset(int line)

Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.

Parameters:

line - a line in the TextBuffer

the - ending offset of the specified line

getParagraphElement

public javax.swing.text.Element getParagraphElement(int pos)

Get the paragraph element containing the given position. This document uses only a single root/leaf element.

Returns:

the paragraph element

getDefaultRootElement

public javax.swing.text.Element getDefaultRootElement()

Fetches the default root element for this document. This document uses only a single root/leaf element.

Specified by:

getDefaultRootElement in interface javax.swing.text.Document

Returns:

the document's line map

getLineMap

public LineMap getLineMap()

Fetches a line map for this document for calculating line positions.

Returns:

the document's line map

getLength

public int getLength()

Returns number of characters of data currently in the document.

Specified by:

getLength in interface javax.swing.text.Document

Returns:

number of characters >= 0

remove

public void remove(int offset,
                   int length)
            throws javax.swing.text.BadLocationException

Removes a portion of the content of the document. This will cause a DocumentEvent of type DocumentEvent.EventType.REMOVE to be sent to the registered DocumentListeners, unless an exception is thrown. The notification will be sent to the listeners by calling the removeUpdate method on the DocumentListeners.

Specified by:

remove in interface javax.swing.text.Document

Parameters:

offset - the offset from the begining >= 0

length - the number of characters to remove >= 0

Throws:

javax.swing.text.BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.

insertString

public void insertString(int offset,
                         java.lang.String str,
                         javax.swing.text.AttributeSet set)
                  throws javax.swing.text.BadLocationException

Inserts a string into the document. This causes a DocumentEvent of type DocumentEvent.EventType.INSERT to be sent to registered DocumentListeners. The offset and length of the generated DocumentEvent will indicate what change was actually made to the Document. An UndoableEditEvent will also be generated.

Specified by:

insertString in interface javax.swing.text.Document

Parameters:

offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.

str - the string to insert

set - the attributes to associate with the inserted content. This may be null if there are no attributes.

Throws:

javax.swing.text.BadLocationException - the given insert position is not a valid position within the document

getText

public java.lang.String getText(int offset,
                                int length)
                         throws javax.swing.text.BadLocationException

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

Specified by:

getText in interface javax.swing.text.Document

Parameters:

offset - the offset into the document representing the desired start of the text >= 0

length - the length of the desired string >= 0

Returns:

the text, in a String of length >= 0

Throws:

javax.swing.text.BadLocationException - some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getText

public void getText(int offset,
                    int length,
                    javax.swing.text.Segment txt)
             throws javax.swing.text.BadLocationException

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

Specified by:

getText in interface javax.swing.text.Document

Parameters:

offset - the offset into the document representing the desired start of the text >= 0

length - the length of the desired string >= 0

txt - the Segment object to return the text in

Throws:

javax.swing.text.BadLocationException - Some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getStartPosition

public javax.swing.text.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 javax.swing.text.Document

Returns:

the position

getEndPosition

public javax.swing.text.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 javax.swing.text.Document

Returns:

the position

createPosition

public javax.swing.text.Position createPosition(int offset)
                                         throws javax.swing.text.BadLocationException

This method allows an application to mark a place in a sequence of character content. This mark can then be used to tracks change as insertions and removals are made in the content. The policy is that insertions always occur prior to the current position (the most common case) unless the insertion location is zero, in which case the insertion is forced to a position that follows the original position.

Specified by:

createPosition in interface javax.swing.text.Document

Parameters:

offset - the offset from the start of the document >= 0

Returns:

the position

Throws:

javax.swing.text.BadLocationException - if the given position does not represent a valid location in the associated document

getRootElements

public javax.swing.text.Element[] getRootElements()

Returns all of the root elements that are defined.

Specified by:

getRootElements in interface javax.swing.text.Document

Returns:

the root element

render

public void render(java.lang.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.

Specified by:

render in interface javax.swing.text.Document

Parameters:

r - a Runnable used to render the model

addDocumentListener

public void addDocumentListener(javax.swing.event.DocumentListener listener)

Registers the given listener to begin receiving notifications when changes are made to the document.

Specified by:

addDocumentListener in interface javax.swing.text.Document

Parameters:

listener - the listener to register

See Also:

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

removeDocumentListener

public void removeDocumentListener(javax.swing.event.DocumentListener listener)

Unregisters the given listener from the notification list so it will no longer receive change updates.

Specified by:

removeDocumentListener in interface javax.swing.text.Document

Parameters:

listener - the listener to register

See Also:

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

addUndoableEditListener

public void addUndoableEditListener(javax.swing.event.UndoableEditListener listener)

Registers the given listener to begin receiving notifications when undoable edits are made to the document.

Specified by:

addUndoableEditListener in interface javax.swing.text.Document

Parameters:

listener - the listener to register

See Also:

UndoableEditEvent

removeUndoableEditListener

public void removeUndoableEditListener(javax.swing.event.UndoableEditListener listener)

Unregisters the given listener from the notification list so it will no longer receive updates.

Specified by:

removeUndoableEditListener in interface javax.swing.text.Document

Parameters:

listener - the listener to register

See Also:

UndoableEditEvent

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent event)

This method gets called when a bound property is changed.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

event - A PropertyChangeEvent object describing the event source and the property that has changed.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener to the listener list. The listener is registered for all properties.

Note that this listener is stored using a WeakReference. This is intentional as part of the editor framework design, to avoid pinning certain UI objects in memory permanently.

Parameters:

listener - The PropertyChangeListener to be added

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Parameters:

listener - The PropertyChangeListener to be removed

firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)

Report a bound property update to any registered listeners. No event is fired if old and new are equal and non-null.

Parameters:

propertyName - The programmatic name of the property that was changed.

oldValue - The old value of the property.

newValue - The new value of the property.

getProperty

public java.lang.Object getProperty(java.lang.Object key)

Gets properties associated with the document. Allows one to store things like the document title, author, etc.

Specified by:

getProperty in interface javax.swing.text.Document

Parameters:

key - a non-null property

Returns:

the properties

putProperty

public void putProperty(java.lang.Object key,
                        java.lang.Object value)

Puts a new property on the list.

Specified by:

putProperty in interface javax.swing.text.Document

Parameters:

key - the non-null property key

value - the property public

fireUndoableEditEvent

protected void fireUndoableEditEvent(javax.swing.undo.UndoableEdit edit)

An internal utility routine to fire UndoableEdit events that are generated by this document to the undoable edit listeners.

Parameters:

edit - the UndoableEdit generated

insertUpdate

public void insertUpdate(TextBuffer buffer,
                         int offset,
                         int count,
                         char[] insertedData)

Provides notification about an insertion into the text buffer.

Specified by:

insertUpdate in interface TextBufferListener

Parameters:

buffer -

offset - the offset where the insert took place

count - the number of characters inserted (insertedData.length)

insertedData - the contents of the insertion

removeUpdate

public void removeUpdate(TextBuffer buffer,
                         int offset,
                         int count,
                         char[] removedData)

Provides notification about a removal from the text buffer.

Specified by:

removeUpdate in interface TextBufferListener

Parameters:

buffer -

offset - the offset where the removal took place

count - the number of characters removed (removedData.length)

removedData - the contents of the removal

attributeUpdate

public void attributeUpdate(TextBuffer buffer,
                            int attribute)

Provides notification regarding a change to one of the buffer attributes. The possible attributes are defined in this interface.

Specified by:

attributeUpdate in interface TextBufferListener

Parameters:

buffer -

attribute - the attribute that changed

addPrePostDocumentListener

public void addPrePostDocumentListener(BasicDocument.PrePostDocumentListener listener)

Registers the given listener to begin receiving pre/post notifications.

Parameters:

listener - the listener to register

removePrePostDocumentListener

public void removePrePostDocumentListener(BasicDocument.PrePostDocumentListener listener)

Unregisters the given listener from receiving pre/post notifications.

Parameters:

listener - the listener to register