com.parabon.client
Class ElementProxy

java.lang.Object
  extended by com.parabon.client.ElementProxy
All Implemented Interfaces:
DataBuffer

public class ElementProxy
extends java.lang.Object
implements DataBuffer

Allows a task to hold a virtual reference to a data element which is modified during task serialization to use actual element contents during task execution. Functions only when part of an object graph serialized as part of a SerializedTask via SerializedTaskSpec, or as part of a checkpoint. Instances should generally only be created on the client side, before task serialization; any instances created with the default constructor during task execution will not behave as expected, instead throwing a IllegalStateException from all method invocations. Will be modified as expected across checkpoints; that is, references to a ElementProxy may be saved as part of a checkpoint.

This class allows any object embedded deep in the object graph to use the contents of an element without needing a reference to the TaskContext from which the element must otherwise be obtained.

To use, simply create an instance of ElementProxy during initial task creation (on the client side) and store it in a serialized field of an object which is part of a SerializedTask (directly or indirectly -- that is, any object serialized as part of a SerializedTask); then, during task execution, use it just as though it was a SerializedTaskContext obtained via SerializedTask.run(). The referenced data element ID will also automatically be marked as required for the task, eliminating the need to explicitly invoke TaskSpec.addRequiredElement().

See Also:
SerializableTask, SerializableTaskSpec, DataBuffer

Nested Class Summary
static class ElementProxy.Placeholder
          Used internally by ElementProxy; should not be referenced used directly by applications.
 
Nested classes/interfaces inherited from interface com.parabon.runtime.DataBuffer
DataBuffer.ReleasedException
 
Constructor Summary
ElementProxy(java.net.URI uri)
          Construct a new ElementProxy.
ElementProxy(java.net.URI uri, DataBuffer contents)
          Construct a new ElementProxy during task execution which points to the existing DataBuffer corresponding to the given data element (obtained via TaskContext.getDataElement()).
 
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.
 java.net.URI getURI()
           
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ElementProxy

public ElementProxy(java.net.URI uri)
Construct a new ElementProxy. This should generally only be used during initial task creation, on the client side, before task serialization; if used during task execution, the ElementProxy will not behave as expected, instead throwing IllegalStateExceptions from all methods.


ElementProxy

public ElementProxy(java.net.URI uri,
                    DataBuffer contents)
Construct a new ElementProxy during task execution which points to the existing DataBuffer corresponding to the given data element (obtained via TaskContext.getDataElement()). This may be used during task execution to create new ElementProxy instances, but is generally not needed by applications.

Method Detail

getURI

public java.net.URI getURI()

getInputStream

public java.io.InputStream getInputStream(int offset)
                                   throws DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
getInputStream in interface DataBuffer
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

public java.io.InputStream getInputStream()
                                   throws DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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).

Specified by:
getInputStream in interface DataBuffer
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.

getLength

public int getLength()
              throws DataBuffer.ReleasedException
Description copied from interface: DataBuffer
Get the current number of bytes contained in this buffer.

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

getOutputStream

public java.io.OutputStream getOutputStream(int offset,
                                            boolean truncateOnClose)
                                     throws java.lang.UnsupportedOperationException,
                                            DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
getOutputStream in interface DataBuffer
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

public java.io.OutputStream getOutputStream(boolean truncateOnClose)
                                     throws java.lang.UnsupportedOperationException,
                                            DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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).

Specified by:
getOutputStream in interface DataBuffer
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.

read

public int read(int offset,
                int len,
                byte[] buffer,
                int bufferOffset)
         throws DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
read in interface DataBuffer
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

public int read(int offset)
         throws DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
read in interface DataBuffer
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.

release

public void release()
Description copied from interface: DataBuffer
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.

Specified by:
release in interface DataBuffer

setLength

public void setLength(int newLength)
               throws java.lang.UnsupportedOperationException,
                      DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
setLength in interface DataBuffer
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.

write

public void write(int offset,
                  int len,
                  byte[] buffer,
                  int bufferOffset)
           throws java.lang.UnsupportedOperationException,
                  DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
write in interface DataBuffer
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

public void write(int offset,
                  int b)
           throws java.lang.UnsupportedOperationException,
                  DataBuffer.ReleasedException
Description copied from interface: DataBuffer
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.

Specified by:
write in interface DataBuffer
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.