oracle.javatools.buffer
Class TextBufferDecorator

java.lang.Object
  oracle.javatools.buffer.ReadTextBufferDecorator
      oracle.javatools.buffer.TextBufferDecorator

All Implemented Interfaces:

ReadTextBuffer, TextBuffer

public abstract class TextBufferDecorator
extends ReadTextBufferDecorator
implements TextBuffer

The TextBufferDecorator is a base decorator for a TextBuffer. This allows additional behavior to be added to a TextBuffer.

Field Summary

protected ForwardingTextBufferListener	_forwarder
protected TextBuffer	_tbuffer The delegate TextBuffer.

Fields inherited from class oracle.javatools.buffer.ReadTextBufferDecorator

_rbuffer

Fields inherited from interface oracle.javatools.buffer.TextBuffer

EOL_CR, EOL_CRLF, EOL_LF, EOL_MACINTOSH, EOL_UNIX, EOL_WINDOWS, READ_ONLY, WRITABLE

Fields inherited from interface oracle.javatools.buffer.ReadTextBuffer

LOCK_STATUS_NONE, LOCK_STATUS_READ, LOCK_STATUS_UNSUPPORTED, LOCK_STATUS_WRITE

Constructor Summary

TextBufferDecorator(TextBuffer buffer)
Constructs the decorator for the delegate buffer.

Method Summary

OffsetMark	addOffsetMark(int offset) Create a new OffsetMark at the given location.
OffsetMark	addOffsetMark(int offset, boolean bias) Create a new OffsetMark at the given location.
void	addTextBufferListener(TextBufferListener listener) Registers the given observer to begin receiving notifications when changes are made to the text buffer either by an insert or remove.
boolean	addWriteLockRequestListener(WriteLockRequestListener listener) Add a write lock request listener on this text buffer.
javax.swing.undo.UndoableEdit	append(char[] data) Appends the indicated data into the text buffer at the end of the buffer.
void	beginEdit() Used to instruct to the text buffer to start a compound edit such that all the changes made between this point and when the endEdit() is called should be combined into a single UndoableEdit record.
void	clearModified() Clears the modification status of the buffer so that it indicates that it has not been modified.
javax.swing.undo.UndoableEdit	endEdit() Used to indicate to the text buffer to end an in progress compound edit.
int	getChangeId() Fetches a change, or incarnation, number that represents the current version of the buffer contents.
java.lang.String	getEOLType() Fetches the EOL terminator type found in the document when its data was read with read( Reader ).
LineMap	getLineMap() Fetches a line map for the text buffer.
java.lang.String	getPlatformEOLType() Fetches the default EOL terminator type associated with this platform as defined by the 'line.separator' property in the system properties.
javax.swing.undo.UndoableEdit	insert(int offset, char[] data) Inserts the indicated data into the text buffer at the given offset.
javax.swing.undo.UndoableEdit	insert(int offset, java.io.Reader reader) Inserts the data from a Reader instance into the text buffer at the given offset.
boolean	isModified() Fetches whether the buffer has been modified since its modification flag was last reset.
boolean	isReadOnly() Fetches whether this TextBuffer is in read-only mode or not.
void	read(java.io.Reader reader) Replaces the current contents of the text buffer with the data from a reader instance.
javax.swing.undo.UndoableEdit	remove(int offset, int count) Removes a range of data from the text buffer.
void	removeOffsetMark(OffsetMark offsetMark) Remove an existing OffsetMark from the text buffer.
void	removeTextBufferListener(TextBufferListener listener) Unregisters the given observer from the notification list so that it will no longer receive change updates.
javax.swing.undo.UndoableEdit	removeToEnd(int offset) Removes data from the text buffer starting at the given offset to the end of the buffer.
void	removeWriteLockRequestListener(WriteLockRequestListener listener) Remove a write lock request listener from this text buffer.
void	setEOLType(java.lang.String eolType) Changes the EOL terminator type associated with this document to the type specified.
void	setReadOnly(boolean readOnly) Sets the read-only mode of this TextBuffer to the requested mode.
boolean	tryWriteLock() Attempts to acquire a write lock on this text buffer in a non-blocking manner.
void	write(java.io.Writer writer) Writes the current contents of the text buffer to a writer instance for the purpose of saving the data.
void	write(java.io.Writer writer, boolean clearModified) Writes the current contents of the text buffer to a writer instance for the purpose of saving the data.
void	writeLock() Attempts to acquire a write lock on this text buffer for the purposes of writing to the text buffer - this is a blocking call.
void	writeLock(boolean checkIfReadOnly) Attempts to acquire a write lock on this text buffer for the purposes of writing to the text buffer - this is a blocking call.
void	writeUnlock() Releases a held write lock on this text buffer.

Methods inherited from class oracle.javatools.buffer.ReadTextBufferDecorator

getChar, getChars, getLength, getLockStatus, getString, getText, readLock, readUnlock, tryReadLock

Methods inherited from class java.lang.Object

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

Methods inherited from interface oracle.javatools.buffer.ReadTextBuffer

getChar, getChars, getLength, getLockStatus, getString, getText, readLock, readUnlock, tryReadLock

Field Detail

_tbuffer

protected TextBuffer _tbuffer

The delegate TextBuffer.

_forwarder

protected ForwardingTextBufferListener _forwarder

Constructor Detail

TextBufferDecorator

public TextBufferDecorator(TextBuffer buffer)

Constructs the decorator for the delegate buffer.

Parameters:

buffer - the buffer that the decorator delegates to

Method Detail

beginEdit

public void beginEdit()
               throws ReadOnlyException

Used to instruct to the text buffer to start a compound edit such that all the changes made between this point and when the endEdit() is called should be combined into a single UndoableEdit record. This guarantees to the client that the buffer will be locked for the duration between beginEdit() and endEdit() for data consistency. This also takes care of locking the buffer, and collecting the individual UndoableEdit objects into a larger compound one.

Note that compound edits may not be nested - it is illegal to call beginEdit() twice in a row without calling endEdit() in between.

Specified by:

beginEdit in interface TextBuffer

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

TextBuffer.endEdit()

endEdit

public javax.swing.undo.UndoableEdit endEdit()

Used to indicate to the text buffer to end an in progress compound edit. This will end the compound edit and returned the single combined UndoableEdit representing all of the changes made between the calls to beginEdit() and endEdit(). If no modifications were made to the buffer since beginEdit() was called, null will be returned.

Specified by:

endEdit in interface TextBuffer

Returns:

the UndoableEdit representing all the changes made

See Also:

TextBuffer.beginEdit()

insert

public javax.swing.undo.UndoableEdit insert(int offset,
                                            char[] data)
                                     throws java.lang.IndexOutOfBoundsException,
                                            ReadOnlyException

Inserts the indicated data into the text buffer at the given offset. This causes all registered TextBufferListeners to be notified by calling insertUpdate(). This will return an UndoableEdit representing this insert change unless a compound edit is in progress in which case null is returned.

Specified by:

insert in interface TextBuffer

Parameters:

offset - the offset at which to insert the new data

data - the text to insert

Returns:

the UndoableEdit representing the insert performed if a compound edit is not in progress

Throws:

java.lang.IndexOutOfBoundsException - if offset is invalid

ReadOnlyException - if the buffer is in read only mode

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit(), TextBuffer.addTextBufferListener(oracle.javatools.buffer.TextBufferListener), TextBuffer.removeTextBufferListener(oracle.javatools.buffer.TextBufferListener)

append

public javax.swing.undo.UndoableEdit append(char[] data)
                                     throws java.lang.IndexOutOfBoundsException,
                                            ReadOnlyException

Appends the indicated data into the text buffer at the end of the buffer. This is a convenience routine which simply performs an insert at the end of the buffer. As with the insert, all registered TextBufferListeners will receive an insertUpdate() notification. The UndoableEdit representing this append will be returned unless a compound edit is in progress.

Specified by:

append in interface TextBuffer

Parameters:

data - the text to insert

Returns:

the UndoableEdit representing the append performed if a compound edit is not in progress

Throws:

ReadOnlyException - if the buffer is in read only mode

java.lang.IndexOutOfBoundsException - this exception is not expected as there are no offsets being passed. It is just to be consistent since internally, append just cals insert.

See Also:

TextBuffer.insert(int, char[]), TextBuffer.beginEdit(), TextBuffer.endEdit(), TextBuffer.addTextBufferListener(oracle.javatools.buffer.TextBufferListener), TextBuffer.removeTextBufferListener(oracle.javatools.buffer.TextBufferListener)

remove

public javax.swing.undo.UndoableEdit remove(int offset,
                                            int count)
                                     throws java.lang.IndexOutOfBoundsException,
                                            ReadOnlyException

Removes a range of data from the text buffer. This causes all registered TextBufferListeners to be notified by calling removeUpdate(). This will return an UndoableEdit representing this removal change unless a compound edit is in progress in which case null is returned.

Specified by:

remove in interface TextBuffer

Parameters:

offset - the offset at which to remove data

count - number of characters to remove

Returns:

the UndoableEdit representing the remove performed if a compound edit is not in progress

Throws:

java.lang.IndexOutOfBoundsException - if offset or count is invalid

ReadOnlyException - if the buffer is in read only mode

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit()

removeToEnd

public javax.swing.undo.UndoableEdit removeToEnd(int offset)
                                          throws java.lang.IndexOutOfBoundsException,
                                                 ReadOnlyException

Removes data from the text buffer starting at the given offset to the end of the buffer. This is a convenience routine which simply calls remove in turn. As with the remove, all registered TextBufferListeners will receive a removeUpdate notification. The UndoableEdit representing this removal will be returned unless a compound edit is in progress.

Specified by:

removeToEnd in interface TextBuffer

Parameters:

offset - the offset at which to remove data

Returns:

the UndoableEdit representing the remove performed if a compound edit is not in progress

Throws:

java.lang.IndexOutOfBoundsException - if offset is invalid

ReadOnlyException - if the buffer is in read only mode

See Also:

TextBuffer.remove(int, int), TextBuffer.beginEdit(), TextBuffer.endEdit()

getLineMap

public LineMap getLineMap()

Fetches a line map for the text buffer. This can be used to locate line boundaries as well as map from lines to offsets (and vice versa.)

Specified by:

getLineMap in interface TextBuffer

Returns:

the line map for the text buffer

addTextBufferListener

public void addTextBufferListener(TextBufferListener listener)

Registers the given observer to begin receiving notifications when changes are made to the text buffer either by an insert or remove. Since the change notification is sent on the same thread making the change, observers can assume that a read lock has already been acquired for the duration of the notification (on the notification thread.)

Specified by:

addTextBufferListener in interface TextBuffer

Parameters:

listener - the observer to register

See Also:

ReadTextBuffer.readLock()

removeTextBufferListener

public void removeTextBufferListener(TextBufferListener listener)

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

Specified by:

removeTextBufferListener in interface TextBuffer

Parameters:

listener - the observer to unregister

setReadOnly

public void setReadOnly(boolean readOnly)

Sets the read-only mode of this TextBuffer to the requested mode.

Specified by:

setReadOnly in interface TextBuffer

Parameters:

readOnly - the new mode to set, READ_ONLY to mark as read-only, WRITABLE to allow modifications

isReadOnly

public boolean isReadOnly()

Fetches whether this TextBuffer is in read-only mode or not.

Specified by:

isReadOnly in interface TextBuffer

Returns:

true if this text buffer is marked as read only

writeLock

public void writeLock()
               throws ReadOnlyException

Attempts to acquire a write lock on this text buffer for the purposes of writing to the text buffer - this is a blocking call. Note that this is equivalent to a exclusive lock - clients requesting a read lock are blocked until the write lock is freed.

Clients may acquire a writeLock explicitly if they have multiple changes to make in the text buffer, to ensure that the changes will not be interleaved with another client's changes.

Specified by:

writeLock in interface TextBuffer

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

ReadTextBuffer.readLock()

writeLock

public void writeLock(boolean checkIfReadOnly)
               throws ReadOnlyException

Attempts to acquire a write lock on this text buffer for the purposes of writing to the text buffer - this is a blocking call. Note that this is equivalent to a exclusive lock - clients requesting a read lock are blocked until the write lock is freed.

Clients may acquire a writeLock explicitly if they have multiple changes to make in the text buffer, to ensure that the changes will not be interleaved with another client's changes.

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.

Specified by:

writeLock in interface TextBuffer

Throws:

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

See Also:

ReadTextBuffer.readLock()

tryWriteLock

public boolean tryWriteLock()
                     throws ReadOnlyException

Attempts to acquire a write lock on this text buffer in a non-blocking manner. Returns true if the write lock was acquired, or false if a write lock could not be acquired. This call returns immediately. Note that successful calls to tryWriteLock() (i.e., where it returns true) must be matched by a call to writeUnlock().

Specified by:

tryWriteLock in interface TextBuffer

Returns:

true if the lock was acquired, false if the lock was not acquired

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

writeLock(), ReadTextBuffer.tryReadLock()

writeUnlock

public void writeUnlock()

Releases a held write lock on this text buffer.

Specified by:

writeUnlock in interface TextBuffer

addWriteLockRequestListener

public boolean addWriteLockRequestListener(WriteLockRequestListener listener)

Description copied from interface: TextBuffer

Add a write lock request listener on this text buffer.

Specified by:

addWriteLockRequestListener in interface TextBuffer

Parameters:

listener - the listener to be addded

Returns:

true if there are already other threads waiting for the write lock, false otherwise

removeWriteLockRequestListener

public void removeWriteLockRequestListener(WriteLockRequestListener listener)

Description copied from interface: TextBuffer

Remove a write lock request listener from this text buffer.

Specified by:

removeWriteLockRequestListener in interface TextBuffer

Parameters:

listener - the listener to be removed

addOffsetMark

public OffsetMark addOffsetMark(int offset)

Create a new OffsetMark at the given location. This OffsetMark will bias to the right of the given location.

Specified by:

addOffsetMark in interface TextBuffer

Parameters:

offset - the offset to stick to

Returns:

the OffsetMark for tracking the offset

See Also:

OffsetMark, removeOffsetMark(oracle.javatools.buffer.OffsetMark)

addOffsetMark

public OffsetMark addOffsetMark(int offset,
                                boolean bias)

Create a new OffsetMark at the given location. The bias can be either OffsetMark.BIAS_RIGHT or OffsetMark.BIAS_LEFT.

Specified by:

addOffsetMark in interface TextBuffer

Parameters:

offset - the offset to stick to

bias - the side of the offset to bias or stick to

Returns:

the OffsetMark for tracking the offset

See Also:

OffsetMark, removeOffsetMark(oracle.javatools.buffer.OffsetMark)

removeOffsetMark

public void removeOffsetMark(OffsetMark offsetMark)

Remove an existing OffsetMark from the text buffer. Since OffsetMarks persist until they are removed explicitly, clients must remove OffsetMarks they created to ensure proper resource release.

Specified by:

removeOffsetMark in interface TextBuffer

Parameters:

offsetMark - the mark to remove

See Also:

OffsetMark, addOffsetMark(int)

isModified

public boolean isModified()

Fetches whether the buffer has been modified since its modification flag was last reset.

Specified by:

isModified in interface TextBuffer

Returns:

whether the buffer has been modified

clearModified

public void clearModified()

Clears the modification status of the buffer so that it indicates that it has not been modified.

Specified by:

clearModified in interface TextBuffer

getChangeId

public int getChangeId()

Fetches a change, or incarnation, number that represents the current version of the buffer contents. The incarnation numbers of the buffer before and after a mutation (insert, remove, read, append, removeToEnd) are guaranteed to be different (though not necessarily sequential), and unique until the set of int's is exhausted (at which point they may repeat.)

Specified by:

getChangeId in interface TextBuffer

Returns:

the current change id of the buffer

read

public void read(java.io.Reader reader)
          throws java.io.IOException

Replaces the current contents of the text buffer with the data from a reader instance. Previous contents are discarded. Currently this operation is not undoable. If an error occurs while reading the file, the contents of the file will simply be empty. This operation cannot be performed while a compound edit is in progress.

Note that this call will reset the read-only status of the text buffer back to WRITABLE.

Specified by:

read in interface TextBuffer

Parameters:

reader - a Reader instance from which to read text data

Throws:

java.io.IOException - as thrown by the stream if an error occurs while reading data

insert

public javax.swing.undo.UndoableEdit insert(int offset,
                                            java.io.Reader reader)
                                     throws java.lang.IndexOutOfBoundsException,
                                            java.io.IOException,
                                            ReadOnlyException

Inserts the data from a Reader instance into the text buffer at the given offset. This causes all registered TextBufferListeners to be notified by calling insertUpdate(). This will return an UndoableEdit representing this insert change unless a compound edit is in progress in which case null is returned.

Specified by:

insert in interface TextBuffer

Parameters:

offset - the offset at which to insert the new data

reader - a Reader instance from which to read text data

Returns:

the UndoableEdit representing the insert performed if a compound edit is not in progress

Throws:

java.lang.IndexOutOfBoundsException - if offset is invalid

ReadOnlyException - if the buffer is in read only mode

java.io.IOException - as thrown by the stream if an error occurs while reading data

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit(), TextBuffer.addTextBufferListener(oracle.javatools.buffer.TextBufferListener), TextBuffer.removeTextBufferListener(oracle.javatools.buffer.TextBufferListener)

write

public void write(java.io.Writer writer)
           throws java.io.IOException

Writes the current contents of the text buffer to a writer instance for the purpose of saving the data. Currently is operation is not undoable. If an error occurs while writing out the data, the destination document will be in an unknown state. This operation cannot be performed while a compound edit is in progress. This call has a side effect of clearing the modified status of the TextBuffer.

Specified by:

write in interface TextBuffer

Parameters:

writer - a Writer instance to which to write the text data

Throws:

java.io.IOException - as thrown by the stream if an error occurs while writing data

write

public void write(java.io.Writer writer,
                  boolean clearModified)
           throws java.io.IOException

Writes the current contents of the text buffer to a writer instance for the purpose of saving the data. Currently is operation is not undoable. If an error occurs while writing out the data, the destination document will be in an unknown state. This operation cannot be performed while a compound edit is in progress.

Specified by:

write in interface TextBuffer

Parameters:

writer - a Writer instance to which to write the text data

clearModified - whether the "modified" state of the buffer should be cleared

Throws:

java.io.IOException - as thrown by the stream if an error occurs while writing data

getPlatformEOLType

public java.lang.String getPlatformEOLType()

Fetches the default EOL terminator type associated with this platform as defined by the 'line.separator' property in the system properties.

Specified by:

getPlatformEOLType in interface TextBuffer

Returns:

the platform default EOL terminator

getEOLType

public java.lang.String getEOLType()

Fetches the EOL terminator type found in the document when its data was read with read( Reader ). The default EOL terminator is defined as the predominant (majority) terminator used in the document.

Specified by:

getEOLType in interface TextBuffer

Returns:

the default EOL terminator for the document, to be used when writing the document back out

setEOLType

public void setEOLType(java.lang.String eolType)
                throws ReadOnlyException

Changes the EOL terminator type associated with this document to the type specified. This allows clients to force the buffer to be saved with an EOL terminator for a particular platform type.

Specified by:

setEOLType in interface TextBuffer

Parameters:

eolType - the EOL terminator type to use

Throws:

ReadOnlyException - if the buffer is in read only mode