oracle.javatools.buffer
Class AbstractTextBuffer

java.lang.Object
  oracle.javatools.buffer.AbstractTextBuffer

All Implemented Interfaces:

ReadTextBuffer, TextBuffer

public abstract class AbstractTextBuffer
extends java.lang.Object
implements TextBuffer

The AbstractTextBuffer class is a starting point for classes implementing the TextBuffer interface. It takes care of providing a basic implementation for some of the functionality (such as locking or line map) of the TextBuffer interface.

This is declared package-private intentionally as it is part of the implementation, and not part of the published API.

Implementation Notes on Change Id

The Change ID is tagged to a "version" of a buffer's contents. It is guaranteed to be different for two versions of buffer contents that are different (but not vice versa.) It is used for two purposes:

• It is used for tracking modified state by recording the change id of the buffer contents that correspond to an unmodified state. Updating the change id in response to a mutation automatically marks the buffer as modified. Similarly, restoring the change id (in response to an undo) to one that is considered "unmodified" automatically marks the buffer as unmodified.
• It is used for enforcing ordering when applying undos. Undos that are not in sequence will result in an exception when trying to apply them.
• Lastly, it is used for enforcing when undos can be merged - they can be merged only if they have equivalent end change id's for the first undo, and start change id's for the second undo. This guarantees that they are consecutive edits. This is needed to help support merge functionality in the editor.

Since change id's are taken from the set of int's, they will invariably repeat over time. This implementation should not be used for a buffer that is heavily modified over a very long period of time without clearing the modified state. For such purposes, this implementation should be changed to use a long field instead.

See Also:

TextBuffer

Nested Class Summary

static class

AbstractTextBuffer.UndoState The UndoState is a layer of indirection between the TextBuffer and UndoableTextEdit's to allow undo's to be detached from the TextBuffer and reattach to a TextBuffer with the same buffer contents.

Field Summary

protected ReadWriteLock	bufferLock The lock used for read/write locking.
protected static char[]	EMPTY_CHARS Private constant for an empty array if trying to call getChars() with length 0.
protected static char	EOF_MARKER Constant for marking the end of the buffer - primarily for debugging purposes.
protected static java.lang.String	platformEOLType Stores the platform EOL type - default is Windows if we can't obtain one from the system.

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

protected

AbstractTextBuffer(ReadWriteLock lockToUse) Initialize this abstract class using the given lock instance to use.

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.
protected void	applyInsert(int offset, char[] data, int oldChangeId) Re-inserts the data based on stored undo information.
protected void	applyRemove(int offset, char[] data, int oldChangeId) Re-removes the data based on stored undo information.
protected boolean	attachUndoState(AbstractTextBuffer.UndoState state) Reattach the UndoState to this TextBuffer.
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.
protected AbstractTextBuffer.UndoState	copyUndoState() Copy the UndoState from this TextBuffer.
protected AbstractTextBuffer.UndoState	detachUndoState() Detach the UndoState from this TextBuffer.
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.
abstract char	getChar(int offset) Fetches the character from the given offset.
char[]	getChars(int offset, int length) Fetches a number of characters from the indicated offset in the buffer.
protected abstract char[]	getCharsImpl(int offset, int length) Internal version of getChars() for subclasses to override.
java.lang.String	getEOLType() Fetches the EOL terminator type found in the document when its data was read with read( Reader ).
abstract int	getLength() Fetches the number of characters in this buffer.
LineMap	getLineMap() Fetches a line map for the text buffer.
int	getLockStatus() Fetch the lock status for the current thread only.
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.
java.lang.String	getString(int offset, int length) Fetches a number of characters from the indicated offset in the buffer and returns it as a String.
protected abstract java.lang.String	getStringImpl(int offset, int length) Internal version of getString() for subclasses to override.
void	getText(int offset, int length, javax.swing.text.Segment segment) Fetches the text contained within the given section of the TextBuffer The Segment object is provided by the caller.
protected abstract void	getTextImpl(int offset, int length, javax.swing.text.Segment segment) Internal version of getText() for subclasses to override.
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.
protected void	insertImpl(int offset, char[] data) Internal version of insert() for subclasses to override.
protected abstract void	insertImpl(int offset, char[] data, int dataOffset, int dataLength) Internal version of insert() for subclasses to override.
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.
protected javax.swing.undo.UndoableEdit	normalizedInsert(int offset, char[] data) Inserts the indicated data into the text buffer at the given offset, without performing EOL normalization.
protected void	read(oracle.javatools.buffer.EOLNormalizer normalizer) Read implementation that takes care of locking, notification, undo, and so on, and delegates the read to a normalizer instance.
void	read(java.nio.channels.FileChannel channel, java.nio.charset.CharsetDecoder decoder) Replaces the current contents of the text buffer with the data from a file channel instance and given character set decorder.
void	read(java.io.Reader reader) Replaces the current contents of the text buffer with the data from a reader instance.
void	readLock() Attempts to acquire a read lock on this text buffer for the purposes of reading the text buffer - this is a blocking call.
void	readUnlock() Releases a held read lock on this text buffer.
javax.swing.undo.UndoableEdit	remove(int offset, int count) Removes a range of data from the text buffer.
protected abstract void	removeImpl(int offset, int count) Internal version of remove() for subclasses to override.
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	tryReadLock() Attempts to acquire a read lock on this buffer in a non-blocking manner.
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, and closes the writer.
void	write(java.io.Writer writer, boolean clearModified) Writes the current contents of the text buffer to a writer, and closes the writer.
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 java.lang.Object

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

Field Detail

EOF_MARKER

protected static final char EOF_MARKER

Constant for marking the end of the buffer - primarily for debugging purposes.

See Also:

Constant Field Values

EMPTY_CHARS

protected static final char[] EMPTY_CHARS

Private constant for an empty array if trying to call getChars() with length 0.

platformEOLType

protected static java.lang.String platformEOLType

Stores the platform EOL type - default is Windows if we can't obtain one from the system.

bufferLock

protected final ReadWriteLock bufferLock

The lock used for read/write locking.

Constructor Detail

AbstractTextBuffer

protected AbstractTextBuffer(ReadWriteLock lockToUse)

Initialize this abstract class using the given lock instance to use.

Parameters:

lockToUse - the ReadWriteLock instance to use for this buffer instance

Method Detail

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

getLength

public abstract int getLength()

Fetches the number of characters in this buffer.

Specified by:

getLength in interface ReadTextBuffer

Returns:

length of buffer

getChar

public abstract char getChar(int offset)
                      throws java.lang.IndexOutOfBoundsException

Fetches the character from the given offset.

Specified by:

getChar in interface ReadTextBuffer

Parameters:

offset - the offset in the buffer to get the character from

Returns:

the character at the given offset

Throws:

java.lang.IndexOutOfBoundsException - if offset is invalid

getChars

public char[] getChars(int offset,
                       int length)
                throws java.lang.IndexOutOfBoundsException

Fetches a number of characters from the indicated offset in the buffer. If length is zero, implementations should return a zero-length array, such as AbstractTextBuffer.EMPTY_CHARS.

Specified by:

getChars in interface ReadTextBuffer

Parameters:

offset - the offset in the buffer to start from

length - number of characters to fetch

Returns:

an array containing the requested characters

Throws:

java.lang.IndexOutOfBoundsException - if offset or length are invalid

getCharsImpl

protected abstract char[] getCharsImpl(int offset,
                                       int length)
                                throws java.lang.IndexOutOfBoundsException

Internal version of getChars() for subclasses to override. Fetches a number of characters from the indicated offset in the buffer.

Parameters:

offset - the offset in the buffer to start from

length - number of characters to fetch

Returns:

an array containing the requested characters

Throws:

java.lang.IndexOutOfBoundsException - if offset or length are invalid

getString

public java.lang.String getString(int offset,
                                  int length)
                           throws java.lang.IndexOutOfBoundsException

Fetches a number of characters from the indicated offset in the buffer and returns it as a String. If the length is zero, a zero-length String will be returned.

Specified by:

getString in interface ReadTextBuffer

Parameters:

offset - the offset in the buffer to start from

length - number of characters to fetch

Returns:

a String containing the requested characters

Throws:

java.lang.IndexOutOfBoundsException - if offset or length are invalid

getStringImpl

protected abstract java.lang.String getStringImpl(int offset,
                                                  int length)
                                           throws java.lang.IndexOutOfBoundsException

Internal version of getString() for subclasses to override. Fetches a number of characters from the indicated offset in the buffer as a String

Parameters:

offset - the offset in the buffer to start from

length - number of characters to fetch

Returns:

a String containing the requested characters

Throws:

java.lang.IndexOutOfBoundsException - if offset or length are invalid

getText

public void getText(int offset,
                    int length,
                    javax.swing.text.Segment segment)
             throws java.lang.IndexOutOfBoundsException

Fetches the text contained within the given section of the TextBuffer The Segment object is provided by the caller.

Specified by:

getText in interface ReadTextBuffer

Parameters:

offset - the offset into the buffer representing the desired start of the data >= 0

length - the length of the desired data >= 0

segment - the caller's Segment object to return the data in

Throws:

java.lang.IndexOutOfBoundsException

See Also:

Document.getText(int, int)

getTextImpl

protected abstract void getTextImpl(int offset,
                                    int length,
                                    javax.swing.text.Segment segment)
                             throws java.lang.IndexOutOfBoundsException

Internal version of getText() for subclasses to override. Fetches the text contained within the given section of the TextBuffer The Segment object is provided by the caller.

Parameters:

offset - the offset into the buffer representing the desired start of the data >= 0

length - the length of the desired data >= 0

segment - the caller's Segment object to return the data in

Throws:

java.lang.IndexOutOfBoundsException

See Also:

Document.getText(int, int)

insert

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

Inserts the indicated data into the text buffer at the given offset. This causes all registered TextBufferListeners to be notified by calling insertUpdate().

Specified by:

insert in interface TextBuffer

Parameters:

offset - the offset at which to insert the new data

data - the text to insert

Returns:

an UndoableEdit representing this insert change unless a compound edit is in progress

Throws:

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)

normalizedInsert

protected javax.swing.undo.UndoableEdit normalizedInsert(int offset,
                                                         char[] data)
                                                  throws ReadOnlyException

Inserts the indicated data into the text buffer at the given offset, without performing EOL normalization. This should only be called if you know that the given data only contains '\n' terminators. This causes all registered TextBufferListeners to be notified by calling insertUpdate().

Parameters:

offset - the offset at which to insert the new data

data - the text to insert

Returns:

an UndoableEdit representing this insert change unless a compound edit is in progress

Throws:

ReadOnlyException - if the buffer is in read only mode

applyInsert

protected void applyInsert(int offset,
                           char[] data,
                           int oldChangeId)
                    throws ReadOnlyException

Re-inserts the data based on stored undo information. This will also restore the change id information so that when the insertUpdate() is fired, the information in the text buffer is correct. This method must be kept in sync with the one above (minus Undo support.)

Parameters:

offset - the offset at which to insert the old data

data - the text to insert

oldChangeId - what to restore the old change id to

Throws:

ReadOnlyException

append

public javax.swing.undo.UndoableEdit append(char[] data)
                                     throws 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.

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

See Also:

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

insertImpl

protected void insertImpl(int offset,
                          char[] data)

Internal version of insert() for subclasses to override. Inserts the indicated data into the text buffer at the given offset.

Parameters:

offset - the offset at which to insert the new data

data - the text to insert

insertImpl

protected abstract void insertImpl(int offset,
                                   char[] data,
                                   int dataOffset,
                                   int dataLength)

Internal version of insert() for subclasses to override. Inserts the indicated data into the text buffer at the given offset.

Parameters:

offset - the offset at which to insert the new data

data - the text to insert

dataOffset - the offset in the array where the data starts

dataLength - the length of the data to insert

remove

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

Removes a range of data from the text buffer. This causes all registered TextBufferListeners to be notified by calling removeUpdate().

Specified by:

remove in interface TextBuffer

Parameters:

offset - the offset at which to remove data

count - number of characters to remove

Returns:

an UndoableEdit representing this remove change unless a compound edit is in progress

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

TextBuffer.beginEdit(), TextBuffer.endEdit()

applyRemove

protected void applyRemove(int offset,
                           char[] data,
                           int oldChangeId)
                    throws ReadOnlyException

Re-removes the data based on stored undo information. This will also restore the change id information so that when the removeUpdate() is fired, the information in the text buffer is correct. This method must be kept in sync with the one above (minus Undo support.)

Parameters:

offset - the offset at which to remove the old data

data - the data that was removed

oldChangeId - what to restore the old change id to

Throws:

ReadOnlyException

removeToEnd

public javax.swing.undo.UndoableEdit removeToEnd(int offset)
                                          throws 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.

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:

ReadOnlyException - if the buffer is in read only mode

See Also:

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

removeImpl

protected abstract void removeImpl(int offset,
                                   int count)

Internal version of remove() for subclasses to override. Removes a range of data from the text buffer.

Parameters:

offset - the offset at which to remove data

count - number of characters to remove

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

readLock

public void readLock()

Attempts to acquire a read lock on this text buffer for the purposes of reading the text buffer - this is a blocking call. Note that this is equivalent to a shared lock - multiple concurrent readers are allowed to acquire the read lock. Note that a readLock must be acquired when using a LineMap.

Specified by:

readLock in interface ReadTextBuffer

See Also:

TextBuffer.getLineMap(), TextBuffer.writeLock()

tryReadLock

public boolean tryReadLock()

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

Specified by:

tryReadLock in interface ReadTextBuffer

Returns:

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

See Also:

ReadTextBuffer.readLock()

readUnlock

public void readUnlock()

Releases a held read lock on this text buffer.

Specified by:

readUnlock in interface ReadTextBuffer

getLockStatus

public int getLockStatus()

Fetch the lock status for the current thread only. Returns LOCK_STATUS_WRITE if the current thread holds a write lock on this buffer (TextBuffer instances only), LOCK_STATUS_READ if the current thread holds a read lock on this buffer, LOCK_STATUS_NONE if the current thread does not hold any locks on this buffer, or LOCK_STATUS_UNSUPPORTED if this ReadTextBuffer implementation does not support locking.

Specified by:

getLockStatus in interface ReadTextBuffer

Returns:

one of the lock status constants indicating the state of the current thread's locks on this buffer

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:

TextBuffer.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

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().

Specified by:

endEdit in interface TextBuffer

Returns:

the UndoableEdit representing all the changes made

See Also:

TextBuffer.beginEdit()

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.

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

read

public void read(java.nio.channels.FileChannel channel,
                 java.nio.charset.CharsetDecoder decoder)
          throws java.io.IOException

Replaces the current contents of the text buffer with the data from a file channel instance and given character set decorder. 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.

Parameters:

channel - a FileChannel instance to use for reading text data

Throws:

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

read

protected void read(oracle.javatools.buffer.EOLNormalizer normalizer)
             throws java.io.IOException

Read implementation that takes care of locking, notification, undo, and so on, and delegates the read to a normalizer instance.

Parameters:

normalizer - the read normalizer to use

Throws:

java.io.IOException

insert

public javax.swing.undo.UndoableEdit insert(int offset,
                                            java.io.Reader reader)
                                     throws 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().

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.io.IOException - as thrown by the stream if an error occurs while reading data

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)

write

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

Writes the current contents of the text buffer to a writer, and closes the writer. If an exception occurs, the writer is not closed: the destination document may or may not have been altered, depending on the writer. This operation cannot be performed while a compound edit is in progress and is not undoable.

The modified state of the buffer is cleared. Clearing the modified state, if not already cleared, will safely take a write lock, which means that if the caller of this method holds a read lock, that read lock will be released and reacquired during the execution of this method.

Specified by:

write in interface TextBuffer

Parameters:

writer - a Writer to which to write buffer contents.

Throws:

java.io.IOException - if the write throws IOException.

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, and closes the writer. If an exception occurs, the writer is not closed: the destination document may or may not have been altered, depending on the writer. This operation cannot be performed while a compound edit is in progress and is not undoable.

If the buffer state needs to be cleared, this method will safely take a write lock, which means that if the caller of this method holds a read lock, that read lock will be released and reacquired during the execution of this method.

Specified by:

write in interface TextBuffer

Parameters:

writer - a Writer to which to write buffer contents.

clearModified - whether to clear the modified state of the buffer.

Throws:

java.io.IOException - if the write throws IOException.

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

addOffsetMark

public OffsetMark addOffsetMark(int offset)

Create a new OffsetMark at 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, TextBuffer.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, TextBuffer.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)

detachUndoState

protected AbstractTextBuffer.UndoState detachUndoState()

Detach the UndoState from this TextBuffer.

Returns:

the UndoState

copyUndoState

protected AbstractTextBuffer.UndoState copyUndoState()

Copy the UndoState from this TextBuffer.

Returns:

the UndoState as an opaque object

attachUndoState

protected boolean attachUndoState(AbstractTextBuffer.UndoState state)

Reattach the UndoState to this TextBuffer.

Parameters:

state -

Returns:

true if the UndoState can be reattached successfully