Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.0.0)

E17493-01

oracle.javatools.editor
Class BasicDocument

java.lang.Object
  extended by 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
EDIT_BEGIN_ATTRIBUTE, EDIT_END_ATTRIBUTE, 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.
 boolean isCompoundEditInProgress()
          Gets whether a compound edit is in progress.
 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()

isCompoundEditInProgress

public boolean isCompoundEditInProgress()
Gets whether a compound edit is in progress.


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

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.0.0)

E17493-01

Copyright © 1997, 2011, Oracle. All rights reserved.