oracle.javatools.buffer
Interface ReadTextBuffer

All Known Subinterfaces:

TextBuffer

All Known Implementing Classes:

AbstractTextBuffer, CharArrayReadTextBuffer, HistoryReadTextBuffer, ReadTextBufferDecorator, TextBufferDecorator

public interface ReadTextBuffer

The ReadTextBuffer interface provides a subset of the TextBuffer methods for read-only access to text data. The parser package is written to use this interface for accessing the text data of a document instead of a flat char[] to give flexibility to parser clients in the design of their text data model.

Note that getChar(), getChars(), getString() and getText() are declared to throw an IndexOutOfBoundsException for invalid offset/length parameters. This means that TextBuffer implementations are not required to provide range checking on offset or length parameters (and are actually encouraged not to.)

This also means that TextBuffer clients must either do their own range checking, or be prepared to catch the IndexOutOfBoundsException (which is a RuntimeException.) All clients in the parser package must catch the IndexOutOfBoundsException.

Design Decisions:

• Why throw an exception instead of doing range checking?

  The answer to this question actually depends on the use scenario. Since this interface is being used for the parser, we examined the length of buffers that will be parsed. The average Java file in JDK 1.3 is around 10k, while the average Java file in the oracle.jdeveloper package is around 4k. Considering that the exception when we encounter the end of the buffer while parsing, is throwing and catching the exception more expensive than 10,000 range checks?

  Again, we did some informal measurements of the cost of throwing and catching an exception versus performing a range check (which generally does not expect to encounter an error), the cost of the exception was comparable to 400 if checks.

  Since most of the files we expect to parse will be reasonably long (>1k), it makes sense to dispense with the range checks in this TextBuffer interface.

• Why use a TextBuffer interface instead of a flat char[]?

  It turns out that the overhead of using a TextBuffer interface to access the buffer data is not very great, provided no range checking is done. If you compare the running time of the following loop:

       int bufferSize = buffer.length;  // buffer is char[]
       for ( int i = 0; i < bufferSize; i++ )
       {
         if ( buffer[i] == '\n' )
         {
           // do something
         }
       } 

  versus the running time of:

       int bufferSize = buffer.getLength();  // buffer is TextBuffer
       for ( int i = 0; i < bufferSize; i++ )
       {
         if ( buffer.getChar( i ) == '\n' )
         {
           // do something
         }
       } 

  it turns out that using the TextBuffer interface is not too much slower than using the char[] directly. With some informal measurements (System.currentTimeMillis() using a large buffer), using the TextBuffer interface takes about 10-25% longer than a straight char[] depending on the VM (10% for Hotspot, 25% for OJVM.)

Note that this interface contains read locking routines though it is not strictly necessary for a read-only interface. In fact, the readLock() and readUnlock() implementations for a ReadTextBuffer backed by a char[] or String are NOP implementations. These two methods are here (instead of in TextBuffer) to support clients that must work with both ReadTextBuffers and TextBuffer instances in a uniform way, such as JOT in JDeveloper.

If you know that the underlying text buffer is backed by a char[] or String, and was created using TextBufferFactory.createReadTextBuffer(), then locking is not needed. If you are not sure, use the readLock() and readUnlock() calls to be safe.

Field Summary

static int	LOCK_STATUS_NONE Status constant indicating that the current thread does not hold any locks on this ReadTextBuffer.
static int	LOCK_STATUS_READ Status constant indicating that the current thread holds a read lock on this ReadTextBuffer.
static int	LOCK_STATUS_UNSUPPORTED Status constant indicating that locking is not supported by this ReadTextBuffer implementation.
static int	LOCK_STATUS_WRITE Status constant indicating that the current thread holds a write lock on this ReadTextBuffer (this can be returned only by TextBuffer instances).

Method Summary

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.
int	getLength() Fetches the number of characters in this buffer.
int	getLockStatus() Fetch the lock status for the current thread only.
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.
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.
void	readLock() Attempts to acquire a read lock on this text buffer for the purposes of reading the buffer - this is a blocking call.
void	readLockInterruptibly() Attempts to acquire a read lock on this text buffer for the purposes of reading the buffer - this is a blocking call.
void	readUnlock() Releases a held read lock on this text buffer.
boolean	tryReadLock() Attempts to acquire a read lock on this buffer in a non-blocking manner.

Field Detail

LOCK_STATUS_WRITE

static final int LOCK_STATUS_WRITE

Status constant indicating that the current thread holds a write lock on this ReadTextBuffer (this can be returned only by TextBuffer instances).

See Also:

Constant Field Values

LOCK_STATUS_READ

static final int LOCK_STATUS_READ

Status constant indicating that the current thread holds a read lock on this ReadTextBuffer.

See Also:

Constant Field Values

LOCK_STATUS_NONE

static final int LOCK_STATUS_NONE

Status constant indicating that the current thread does not hold any locks on this ReadTextBuffer.

See Also:

Constant Field Values

LOCK_STATUS_UNSUPPORTED

static final int LOCK_STATUS_UNSUPPORTED

Status constant indicating that locking is not supported by this ReadTextBuffer implementation. The readLock(), tryReadLock(), and readUnlock() calls are no-ops.

See Also:

Constant Field Values

Method Detail

getLength

int getLength()

Fetches the number of characters in this buffer.

Returns:

length of buffer

getChar

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

Fetches the character from the given offset.

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

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, a zero-length array will be returned.

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

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.

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

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.

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)

readLock

void readLock()

Attempts to acquire a read lock on this text buffer for the purposes of reading the 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 for TextBuffer objects, 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:

TextBuffer.getLineMap(), TextBuffer.writeLock()

readLockInterruptibly

void readLockInterruptibly()
                           throws java.lang.InterruptedException

Attempts to acquire a read lock on this text buffer for the purposes of reading the 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 for TextBuffer objects, 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.

Throws:

java.lang.InterruptedException - if the current thread is in or gets put in the interrupted state. The interrupted state is cleared when this exception is thrown.

See Also:

TextBuffer.getLineMap(), TextBuffer.writeLock()

tryReadLock

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

Returns:

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

See Also:

readLock()

readUnlock

void readUnlock()

Releases a held read lock on this text buffer.

getLockStatus

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.

Returns:

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