oracle.javatools.buffer
Interface TextBuffer

All Superinterfaces:

ReadTextBuffer

public interface TextBuffer

extends ReadTextBuffer

The TextBuffer interface describes a class which can be used for managing the raw text content of a document. It provides services to higher level document classes, such as shared/exclusive locking services, buffer modification through insert/removal, buffer change notification, and mark services.

This TextBuffer interface acts as a unified data or buffer model between the editor and IDE packages - this allows us to build implementation layers above this Content layer to satisfy the requirements of each.

Terminology Notes:

The implementation refers to implementations of the TextBuffer interface, such as an ArrayTextBuffer. The client refers to clients which use a TextBuffer, such as an editor document or parser.

LineMap Service:

The TextBuffer provides line map services for clients to use for determining line boundaries. Method calls are available for mapping a given buffer offset to a line, and for obtaining the start and end offsets of a line. Please refer to the LineMap interface for more details on using the LineMap.

OffsetMark Service:

OffsetMarks are used to bookmark specific offsets in the text buffer. Method calls are available for adding or removing marks, and for getting or changing the offset location for specific marks. Please refer to the OffsetMark interface for more details on using OffsetMarks.

UndoableEdit Notes:

UndoableEdits are generated by the insert() and remove() methods to represent the changes made to the buffer. These can be used as building blocks to support an Undo mechanism in the client application. It is the responsibility of the client application to manage the UndoableEdits and to apply them in the proper order. Buffer implementations may however use the change id to do some minimum enforcing of undo ordering.

If there are specific changes that should be represented by a single undo operation, the beginEdit() and endEdit() pairs can be used. For example, suppose the user adds a button through a UI designer, which corresponds to adding multiple lines of code in the buffer. The application should call beginEdit(), make the changes to the buffer, then call endEdit(), which will return a single compound UndoableEdit representing all the changes made. Note that calls to the beginEdit() and endEdit() pairs cannot overlap or be nested - that is it is illegal to call beginEdit() if there is already a compound edit in progress.

Note that individual edits within a compound edit should take into account how their offsets and lengths affect each other. For example, let's suppose that the application needs to insert 10 bytes at offset 10, and 5 bytes at offset 20. It should apply them in reverse order:

• insert 5 bytes at offset 20
• insert 10 bytes at offset 10

If it applies them in forward order, the offset shifts must be taken into account:

• insert 10 bytes at offset 10
• insert 5 bytes at offset 30

Locking Notes:

This interface provides locking routines which must be used by clients to ensure data consistency and integrity. Clients must acquire a read lock before retrieving data from this buffer, or accessing information from the line map. As discussed in the ReadTextBuffer interface, implementations are not required to perform range checking on data read requests, such as through getChar(). Clients must either perform their own range checking, or must catch and handle the IndexOutOfBoundsException.

Clients must acquire a write lock before modifying the text buffer through this interface. As a convenience to clients, implementations must implicitly lock the buffer in the insert() and remove() methods. Clients are still encouraged to make use of the writeLock() and writeUnlock() calls, especially when multiple modifications need to be made sequentially.

Modification Notes:

This interface provides some basic support for determining whether a buffer has been modified or not. It does not however provide timestamp information, such as the timestamp for when a modification was made to the text buffer. A buffer is marked as unmodified when it is created, after read() is called, or after clearModified() is called. After an insert(), append(), remove(), or removeToEnd(), a buffer is considered to be modified.

Additionally, the (buffer) implementation is required to update the modification information when applying undos that are generated by the buffer. For example, suppose a buffer is initially unmodified, then an insert made resulting in an UndoableEdit. If that UndoableEdit is then applied, the buffer is required to ensure that the buffer's modified status is also reset back to unmodified as it was before the insert.

Change ID Notes:

This interface provides the getChangeId() method for getting an incarnation number for representing a particular version of the buffer's contents. (Buffer) implementations must guarantee that incarnation numbers of the buffer before and after a mutation are different, though not necessarily in sequence. Implementations must also guarantee that undoing a mutation using an UndoableEdit generated by the buffer will also restore the previous change id as well. For example, suppose the change id for the buffer is 10, then an insert was made resulting in an UndoableEdit and new change id of 12. If that UndoableEdit is then applied (undone), the change id of the buffer must be restored back to 10. If that UndoableEdit is re-applied (redone), the chagne id of the buffer must be restored back to 12.

This can be used by clients to determine whether a buffer has been modified since a particular snapshot. For example, suppose a client uses a parser to build additional client-specific model information based on the text buffer's contents. The client can store the change id for the text buffer at the time the client-specific model information was built to determine, at some later point in the future, whether the text buffer has changed by comparing the stored change id vs. the current change id of the text buffer.

Since possible numbers for the change id come from a finite set (set of int's), the change id numbers may repeat once the set of int's have been exhausted. Until the change id's loop over (repeat), clients are guaranteed that different change id's represent different buffer contents. Load/Save Notes:

This interface provides basic routines for reading and writing the data to and from a persistent storage area, such as a file system, database, network drive, and so on. Additionally, implementations will perform normalization on end-of-line (EOL) terminators such that buffers will contain only LF (\n) characters in memory to simplify the task of dealing with line ends for clients.

The EOL terminator recorded in the buffer is defined as the predominant or majority EOL terminator encountered while reading the data in through the read( Reader ) method. For newly created TextBuffer instances where this method is not called, the platform default EOL terminator will be used. In either case the assigned EOL terminator type will be used when saving the file using the write( Writer ) method.

When the file is read or saved, the modification status of the text buffer will be cleared.

Read-Only Mode Notes:

This interface provides support for marking the buffer as read-only programmatically to restrict modifications to the buffer. This may be useful for example, if the persistent data storage area is read-only.

To retrieve or change the read-only mode of the text buffer, use the setReadOnly() or isReadOnly() method calls.

If the buffer is in read-only mode, any attempts to acquire a write lock will result in a ReadOnlyException to be thrown. This includes calling the following methods: beginEdit(), writeLock() insert(), append(), remove(), removeToEnd(), and setEOLType(). The only exception is read() which will reset the text buffer's read only status back to WRITABLE.

If there is an edit in progress (i.e., someone is holding the write lock), any attempts to change the buffer to read-only will block until the edit is complete.

Although the ReadOnlyException is defined as a RuntimeException (and need not be caught explicitly), implementations are encouraged to catch the exception for thoroughness, in addition to calling isReadOnly() first before attempting any modifications to the buffer.

See Also:

ReadTextBuffer, LineMap, OffsetMark

Field Summary

static java.lang.String	EOL_CR Private constant for a single CR for an EOL terminator.
static java.lang.String	EOL_CRLF Private constant for CR/LF pair for an EOL terminator.
static java.lang.String	EOL_LF Private constant for a single LF for an EOL terminator.
static java.lang.String	EOL_MACINTOSH Private constant for EOL terminators used by Macintosh platforms.
static java.lang.String	EOL_UNIX Private constant for EOL terminators used by UNIX platforms.
static java.lang.String	EOL_WINDOWS Private constant for EOL terminators used by DOS or Windows platforms.
static boolean	READ_ONLY Public constant for use with setReadOnly() to mark the buffer as read only.
static boolean	WRITABLE Public constant for use with setReadOnly() to allow regular modifications to the buffer.

Method Summary

OffsetMark	addOffsetMark(int offset) 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.
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	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.
void	write(java.io.Writer writer) Writes the current contents of the text buffer to a writer instance for the purpose of savingthe 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	writeUnlock() Releases a held write lock on this text buffer.

Methods inherited from interface oracle.javatools.buffer.ReadTextBuffer

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

Field Detail

READ_ONLY

public static final boolean READ_ONLY

Public constant for use with setReadOnly() to mark the buffer as read only.

See Also:

Constant Field Values

WRITABLE

public static final boolean WRITABLE

Public constant for use with setReadOnly() to allow regular modifications to the buffer.

See Also:

Constant Field Values

EOL_CRLF

public static final java.lang.String EOL_CRLF

Private constant for CR/LF pair for an EOL terminator.

See Also:

Constant Field Values

EOL_WINDOWS

public static final java.lang.String EOL_WINDOWS

Private constant for EOL terminators used by DOS or Windows platforms.

See Also:

Constant Field Values

EOL_LF

public static final java.lang.String EOL_LF

Private constant for a single LF for an EOL terminator.

See Also:

Constant Field Values

EOL_UNIX

public static final java.lang.String EOL_UNIX

Private constant for EOL terminators used by UNIX platforms.

See Also:

Constant Field Values

EOL_CR

public static final java.lang.String EOL_CR

Private constant for a single CR for an EOL terminator.

See Also:

Constant Field Values

EOL_MACINTOSH

public static final java.lang.String EOL_MACINTOSH

Private constant for EOL terminators used by Macintosh platforms.

See Also:

Constant Field Values

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.

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

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.

Returns:

the UndoableEdit representing all the changes made

See Also:

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.

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:

beginEdit(), endEdit(), addTextBufferListener(oracle.javatools.buffer.TextBufferListener), 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.

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:

insert(int, char[]), beginEdit(), endEdit(), addTextBufferListener(oracle.javatools.buffer.TextBufferListener), 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.

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:

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

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:

remove(int, int), beginEdit(), 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.)

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

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.

Parameters:

listener - the observer to unregister

setReadOnly

public void setReadOnly(boolean readOnly)

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

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.

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.

Throws:

ReadOnlyException - if the buffer is in read only mode

See Also:

ReadTextBuffer.readLock()

writeUnlock

public void writeUnlock()

Releases a held write lock on this text buffer.

addOffsetMark

public OffsetMark addOffsetMark(int offset)

Create a new OffsetMark at the given location.

Parameters:

offset - the offset to 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.

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.

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.

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

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.

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.

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:

beginEdit(), endEdit(), addTextBufferListener(oracle.javatools.buffer.TextBufferListener), 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 savingthe 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.

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

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.

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.

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.

Parameters:

eolType - the EOL terminator type to use

Throws:

ReadOnlyException - if the buffer is in read only mode