com.parabon.runtime
Interface DataBuffer

All Known Implementing Classes:
ElementProxy, ElementProxy.Placeholder

public interface DataBuffer

The DataBuffer interface allows a task to access and possibly manipulate a flat finite set of bytes, either randomly or via streams. DataBuffer are used to represent task parameters, data elements, checkpoints, intermediate and final results, and as temporary storage buffers for tasks. Task parameters and data elements -- obtained through an argument to the Task.run method and via TaskContext.getDataElement, respectively -- are read-only; attempting to modify them will result in an UnsupportedOperationException. DataBuffers can also be obtained via TaskContext.createDataBuffer; these are read/write and can be used to report checkpoints and * intermediate and final results.

No guarantees are made as to how the contents of a DataBuffer are stored -- they may be stored directly in memory, on disk, accessed over a socket, compressed, or through some combination of methods. An optional hint may be given to TaskContext.createDataBuffer to request a buffer stored either entirely in memory or entirely on disk, if the task knows that it will either be accessing a small amount of data frequently or a large amount infrequently.

A DataBuffer instance may use system resources other than memory, and the runtime system may keep a handle on active instances; because of this, the JVM garbage collection mechanism alone may not be sufficient to efficiently free such resources after they are no longer required by the task. Hence, the release method exists to notify the DataBuffer that a task no longer requires that instance or the data it contains, allowing the DataBuffer to explicitly free any system resources it is holding. This can allow the more efficient execution of the task. However, once release has been called, no other methods may be invoked on the DataBuffer (doing so will cause a DataBuffer.ReleasedException to be thrown), and that DataBuffer may not be passed to any TaskContext method or returned as a task's final results.


Nested Class Summary
static class DataBuffer.ReleasedException
           
 
Method Summary
 java.io.InputStream getInputStream()
          Create an InputStream instance from which to read the contents of this DataBuffer starting at the given offset.
 java.io.InputStream getInputStream(int offset)
          Create an InputStream instance from which to read the contents of this DataBuffer starting at the beginning.
 int getLength()
          Get the current number of bytes contained in this buffer.
 java.io.OutputStream getOutputStream(boolean truncateOnClose)
          Create an OutputStream instance with which data may be written to this DataBuffer starting at the beginning.
 java.io.OutputStream getOutputStream(int offset, boolean truncateOnClose)
          Create an OutputStream instance with which data may be written to this DataBuffer starting at the given offset.
 int read(int offset)
          Read a single byte of data at the supplied offset into this DataBuffer.
 int read(int offset, int len, byte[] buffer, int bufferOffset)
          Read len bytes starting at source offset offset from this DataBuffer into buffer starting at destination offset bufferOffset.
 void release()
          Notify the DataBuffer that the task no longer requires this DataBuffer for either accessing or storing data, allowing the DataBuffer to release any resources it was using.
 void setLength(int newLength)
          Set the length of this buffer in bytes.
 void write(int offset, int b)
          Write a single byte of data at the supplied offset into this DataBuffer.
 void write(int offset, int len, byte[] buffer, int bufferOffset)
          Write len bytes starting at destination offset offset into this DataBuffer from buffer starting at source offset bufferOffset.
 

Method Detail

getLength

int getLength()
              throws DataBuffer.ReleasedException
Get the current number of bytes contained in this buffer.

Returns:
current length of this DataBuffer in bytes
Throws:
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

setLength

void setLength(int newLength)
               throws java.lang.UnsupportedOperationException,
                      DataBuffer.ReleasedException
Set the length of this buffer in bytes. If the requested length is greater than the current length, new bytes will be conceptually appended to the end of the buffer and set to 0. If the requested length is less than the current length, the buffer will be truncated and resources used to store any truncated space may or may not be freed.

Method may only be invoked on read/write DataBuffer instances, such as those returned from TaskContext.createDataBuffer.

Parameters:
newLength - new length of this DataBuffer in bytes
Throws:
java.lang.UnsupportedOperationException - if this DataBuffer is read-only.
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

read

int read(int offset,
         int len,
         byte[] buffer,
         int bufferOffset)
         throws DataBuffer.ReleasedException
Read len bytes starting at source offset offset from this DataBuffer into buffer starting at destination offset bufferOffset. Reads fewer bytes only if the end of the source or destination buffers is hit. Returns the number of bytes actually read.

Parameters:
offset - offset into the DataBuffer's contents at which to start reading
len - number of bytes to read
buffer - buffer into which to read bytes
bufferOffset - offset into destination buffer at which to start copying bytes
Returns:
number of bytes actually read (should be exactly equal to len unless offset+len > getLength())
Throws:
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

read

int read(int offset)
         throws DataBuffer.ReleasedException
Read a single byte of data at the supplied offset into this DataBuffer. Returns the byte read, or -1 if the supplied offset is greater than or equal to the length of this DataBuffer's contents.

Parameters:
offset - offset into the DataBuffer's contents from which to read a byte
Returns:
the byte read, or -1 if offset >= getLength()
Throws:
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

write

void write(int offset,
           int len,
           byte[] buffer,
           int bufferOffset)
           throws java.lang.UnsupportedOperationException,
                  DataBuffer.ReleasedException
Write len bytes starting at destination offset offset into this DataBuffer from buffer starting at source offset bufferOffset. Writes fewer bytes only if the end of the source or destination buffers is hit.

Method may only be invoked on read/write DataBuffer instances, such as those returned from TaskContext.createDataBuffer.

Parameters:
offset - offset into the DataBuffer's contents at which to start writing
len - number of bytes to write
buffer - buffer containing bytes to be written
bufferOffset - offset into source buffer from which to start copying bytes
Throws:
java.lang.UnsupportedOperationException - if this DataBuffer is read-only.
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

write

void write(int offset,
           int b)
           throws java.lang.UnsupportedOperationException,
                  DataBuffer.ReleasedException
Write a single byte of data at the supplied offset into this DataBuffer.

Method may only be invoked on read/write DataBuffer instances, such as those returned from TaskContext.createDataBuffer.

Parameters:
offset - offset into the DataBuffer's contents at which to write a byte
b - byte to be written (only the low-order 8 bits are used)
Throws:
java.lang.UnsupportedOperationException - if this DataBuffer is read-only.
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

getInputStream

java.io.InputStream getInputStream(int offset)
                                   throws DataBuffer.ReleasedException
Create an InputStream instance from which to read the contents of this DataBuffer starting at the beginning.

If this DataBuffer is modified or released after this method is invoked, any subsequent attempt to access this InputStream will result in undefined behavior.

Parameters:
offset - offset into the DataBuffer's contents at which the returned InputStream should start reading
Returns:
a new InputStream instance from which the contents of this DataBuffer can be read, starting at the supplied offset
Throws:
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

getInputStream

java.io.InputStream getInputStream()
                                   throws DataBuffer.ReleasedException
Create an InputStream instance from which to read the contents of this DataBuffer starting at the given offset.

If this DataBuffer is modified or released after this method is invoked, any subsequent attempt to access this InputStream will result in undefined behavior.

Equivalent to getInputStream(0).

Returns:
a new InputStream instance from which the contents of this DataBuffer can be read, starting at the beginning
Throws:
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

getOutputStream

java.io.OutputStream getOutputStream(int offset,
                                     boolean truncateOnClose)
                                     throws java.lang.UnsupportedOperationException,
                                            DataBuffer.ReleasedException
Create an OutputStream instance with which data may be written to this DataBuffer starting at the given offset. The length of the DataBuffer will be extended as necessary if writing continues past its current length. If the truncateOnClose flag was set then when the OutputStream is closed the length of the DataBuffer is set such that the last offset written to the OutputStream is the end of the buffer.

If this DataBuffer is modified by other means or released after this method is invoked, any subsequent attempt to access this OutputStream will result in undefined behavior.

Parameters:
offset - offset into the DataBuffer's contents at which the returned OutputStream should start writing
truncateOnClose - if set, then when the close method is invoked on the returned OutputStream, the length of this DataBuffer will be set equal to the offset of the last byte written via the OutputStream plus one
Returns:
a new OutputStream instance which will write data to the DataBuffer starting at the supplied offset, expanding it as necessary and optionally truncating it when the OutputStream is closed
Throws:
java.lang.UnsupportedOperationException - if this DataBuffer is read-only
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

getOutputStream

java.io.OutputStream getOutputStream(boolean truncateOnClose)
                                     throws java.lang.UnsupportedOperationException,
                                            DataBuffer.ReleasedException
Create an OutputStream instance with which data may be written to this DataBuffer starting at the beginning. The length of the DataBuffer will be extended as necessary if writing continues past its current length. If the truncateOnClose flag was set then when the OutputStream is closed the length of the DataBuffer is set such that the last offset written to the OutputStream is the end of the buffer.

If this DataBuffer is modified by other means or released after this method is invoked, any subsequent attempt to access this OutputStream will result in undefined behavior.

Equivalent to getOutputStream(0, truncateOnClose).

Parameters:
truncateOnClose - if set, then when the close method is invoked on the returned OutputStream, the length of this DataBuffer will be set equal to the offset of the last byte written via the OutputStream plus one
Returns:
a new OutputStream instance which will write data to the DataBuffer starting at the beginning, expanding it as necessary and optionally truncating it then the OutputStream is closed
Throws:
java.lang.UnsupportedOperationException - if this DataBuffer is read-only
DataBuffer.ReleasedException - if this DataBuffer has already been released via a call to DataBuffer.release.

release

void release()
Notify the DataBuffer that the task no longer requires this DataBuffer for either accessing or storing data, allowing the DataBuffer to release any resources it was using. release can be called any time on a DataBuffer, and can be called as many times as desired, though only the first invocation will have an effect. Calling release may free up resources used by this DataBuffer, but after it is called for the first time, calling any other methods on this DataBuffer (other than release) will result in a DataBuffer.ReleasedException being thrown. Similarly, after release is invoked, this DataBuffer may not be passed back to any TaskContext method or returned from Task.run as final results; doing so will result in undefined behavior.