gr.uoa.di.madgik.grs.record
Class Record

java.lang.Object
  extended by gr.uoa.di.madgik.grs.record.Record
All Implemented Interfaces:
IPumpable
Direct Known Subclasses:
GenericRecord

public abstract class Record
extends java.lang.Object
implements IPumpable

This class is the base class for all Records that are handled by the gRS2 set of components. All implementations of this abstract class must define a default constructor without arguments as instances of these classes will be instantiated using reflection based on the existence of a default no arguments constructor. One thing that distinguishes the records belonging to one IBuffer, is the id. This id is set from within the framework once the record is bound to an IBuffer as described in bind(IBuffer). This means that the id of each Record represents the index of the Record within the virtually infinite array of Records managed by the IBuffer

Author:
gpapanikos

Constructor Summary
Record()
           
 
Method Summary
 void bind(IBuffer buffer)
          Binds the Record to the provided IBuffer.
 void deflate(java.io.DataOutput out)
          Deflates the state and data of the implementor in a from capable of reconstructing the exact same instance
 void dispose()
          Disposes all internally kept state, calls extendDispose() and then for every hosted Field, calls Field.dispose()
abstract  void extendDeflate(java.io.DataOutput out)
          The method all Record implementations should implement to add any information they keep during deflate
abstract  void extendDispose()
          Method to be implemented by Record extenders to dispose any internally kept state
abstract  void extendInflate(java.io.DataInput in, boolean reset)
          The method all Record implementations should implement to read any information they deflated
abstract  void extendReceive(java.io.DataInput in)
          The method all Record implementations should implement to read any information they send during transfer
abstract  void extendReceiveFromXML(org.w3c.dom.Element element)
           
abstract  void extendSend(java.io.DataOutput out)
          The method all Record implementations should implement to add any information they keep during transfer
abstract  void extendSendToXML(org.w3c.dom.Document doc, org.w3c.dom.Element element)
           
 void fromXML(org.w3c.dom.Element element)
           
 RecordDefinition getDefinition()
          Retrieves the RecordDefinition associated with this Record.
 int getDefinitionIndex()
          Gets the index of the definition of this Record in the record definitions array provided to the IBuffer
 Field getField(int index)
          Retrieve the Field with the specified index in the fields array
 Field getField(java.lang.String name)
          Retrieve the Field with the specified name
 Field[] getFields()
          Retrieves the Fields this Record hosts
 long getID()
          Retrieves the id of the Record
 void hide()
          Hides the Record from the IBuffer it is currectly bound to so that it won't be disposed by the former.
 void inflate(java.io.DataInput in)
          Inflate the state and data of the implementor as was previously deflated using IPumpable.deflate(DataOutput)
 void inflate(java.io.DataInput in, boolean reset)
          Inflate the state and data of the implementor as was previously deflated using IPumpable.deflate(DataOutput)
 boolean isBoundTo(IBuffer buffer)
          Determines whether this Record is bound to a specific instance of IBuffer
 boolean isRemoteCopy()
          Retrieves if this is the remote copy of the record
 void makeAvailable()
          For all hosted Fields, the method makeAvailable(int)
 void makeAvailable(int fieldIndex)
          For the specified Field with the set index, the method Record#makeAvailable(TransportOverride, int) with a value of IBuffer.TransportOverride.Override
 void makeAvailable(java.lang.String fieldName)
          For the specified Field with the set name, the method Record#makeAvailable(TransportOverride, int) with a value of IBuffer.TransportOverride.Override
 void makeLocal()
          Called by RecordWriter.importRecord(T).
 void markActivity()
          Notifies the IBuffer associated with this Record that some activity has taken place
 void prebind(IBuffer buffer)
          This method performs a pre-bind of the Record to the provided IBuffer to enable the invocation of some other method that needs to have the IBuffer of the record available but before adding the record to the IBuffer properly
 void receive(java.io.DataInput in)
          Receives the state and payload of the Record from a remote sender.
 void receiveFromXML(org.w3c.dom.Element element)
           
 void requestPartial(IBuffer.TransportOverride override, int fieldIndex)
          if the associated IBuffer has a IMirror set, then the IMirror#requestPartial(long, int, TransportOverride, Object) method is used to request additional payload for the specific Field of the Record.
 IBuffer.TransportDirective resolveTransportDirective()
          Resolves the IBuffer.TransportDirective that should be used fir this record.
 void send(java.io.DataOutput out)
          Sends the state and payload of the Record to a remote requester.
 org.w3c.dom.Element sendToXML(org.w3c.dom.Document doc)
           
 void setDefinitionIndex(int index)
          Sets the index of the definition of this Record in the record definitions array provided to the IBuffer
 void setFields(Field[] fields)
          Sets the Fields this Record hosts
 void setRemoteCopy(boolean remoteCopy)
          Set if the current instance of the Record is a remote copy of the original instance of the Record
 void show()
          Reveals a hidden Record to the IBuffer, making available all functionality related to the former.
 org.w3c.dom.Element toXML(org.w3c.dom.Document doc)
           
 void unbind()
          Unbinds the Record from the IBuffer.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Record

public Record()
Method Detail

getID

public long getID()
Retrieves the id of the Record

Returns:
the id

getDefinition

public RecordDefinition getDefinition()
                               throws GRS2RecordDefinitionException,
                                      GRS2BufferException
Retrieves the RecordDefinition associated with this Record. This operation is only available after the bind(IBuffer) method is invoked. This method is typically invoked when a Record is added to an IBuffer

Returns:
the record definition
Throws:
GRS2RecordDefinitionException - if the Record was not properly bind to a IBuffer
GRS2BufferException - the available definitions could not be retrieved from the IBuffer

getDefinitionIndex

public int getDefinitionIndex()
Gets the index of the definition of this Record in the record definitions array provided to the IBuffer

Returns:
the index

setDefinitionIndex

public void setDefinitionIndex(int index)
Sets the index of the definition of this Record in the record definitions array provided to the IBuffer

Parameters:
index - the index

setFields

public void setFields(Field[] fields)
Sets the Fields this Record hosts

Parameters:
fields - the fields

getFields

public Field[] getFields()
Retrieves the Fields this Record hosts

Returns:
the fields

getField

public Field getField(java.lang.String name)
               throws GRS2RecordDefinitionException,
                      GRS2BufferException
Retrieve the Field with the specified name

Parameters:
name - the name of the field as is defined in the Field's FieldDefinition
Returns:
the field or null if the field was not found
Throws:
GRS2RecordDefinitionException - If there was a problem retrieving the available fields definitions
GRS2BufferException - If there was a problem retrieving the definitions from the IBuffer

getField

public Field getField(int index)
Retrieve the Field with the specified index in the fields array

Parameters:
index - the field index
Returns:
the Field

bind

public void bind(IBuffer buffer)
          throws GRS2BufferException,
                 GRS2RecordDefinitionException
Binds the Record to the provided IBuffer. If the record has no definition index defined and the buffer's record definitions only contain a single definition, the only available definition is used by default. The id of the record is set as IBuffer.totalRecords()-1. Therefore the id always coincides with the virtual index of the Record if one considers the Record as being available in an unbounded array of Records. For every Field available in the Record, the Field.setDefinitionIndex(int) as well as Field.bind(Record) method is invoked.

Parameters:
buffer - the IBuffer to bind this record to
Throws:
GRS2BufferException - the IBuffer state does not permit this operation to be completed
GRS2RecordDefinitionException - no usable definition could be found and associated with the Record

unbind

public void unbind()
Unbinds the Record from the IBuffer. The id of the record, its definition index are reset and any information pertaining to partial transfers are reset. The Fields are not unbound from the Record


hide

public void hide()
Hides the Record from the IBuffer it is currectly bound to so that it won't be disposed by the former. All buffer related functionality will not be available until the record is revealed again to the IBuffer


show

public void show()
Reveals a hidden Record to the IBuffer, making available all functionality related to the former. The record still won't be explicitly disposed by the IBuffer


isBoundTo

public boolean isBoundTo(IBuffer buffer)
Determines whether this Record is bound to a specific instance of IBuffer

Parameters:
buffer - the IBuffer which this record will be tested against
Returns:
true if this Record is bound to the IBuffer, false otherwise regardless if the record is bound to another buffer or not bound to any buffer

prebind

public void prebind(IBuffer buffer)
This method performs a pre-bind of the Record to the provided IBuffer to enable the invocation of some other method that needs to have the IBuffer of the record available but before adding the record to the IBuffer properly

Parameters:
buffer - the IBuffer to pre-bind to

markActivity

public void markActivity()
Notifies the IBuffer associated with this Record that some activity has taken place


setRemoteCopy

public void setRemoteCopy(boolean remoteCopy)
Set if the current instance of the Record is a remote copy of the original instance of the Record

Parameters:
remoteCopy - whether or not this is the remote copy

isRemoteCopy

public boolean isRemoteCopy()
Retrieves if this is the remote copy of the record

Returns:
true if it is the remote copy

resolveTransportDirective

public IBuffer.TransportDirective resolveTransportDirective()
                                                     throws GRS2RecordDefinitionException,
                                                            GRS2BufferException
Resolves the IBuffer.TransportDirective that should be used fir this record. In case the defined IBuffer.TransportDirective is set to IBuffer.TransportDirective.Inherit, a call to the bound IBuffer's IBuffer.resolveTransportDirective()

Returns:
the resolved IBuffer.TransportDirective
Throws:
GRS2RecordDefinitionException - the record definition is not available
GRS2BufferException - the buffer is unavailable

deflate

public final void deflate(java.io.DataOutput out)
                   throws GRS2RecordSerializationException
Deflates the state and data of the implementor in a from capable of reconstructing the exact same instance Deflates the state and payload of the Record to the provided stream. After deflating the internally kept information, a call to extendDeflate(DataOutput) is made and then for each field hosted, a call to Field.deflate(DataOutput) is made

Specified by:
deflate in interface IPumpable
Parameters:
out - the stream to deflate to
Throws:
GRS2RecordSerializationException - there was a problem serializing the information

send

public final void send(java.io.DataOutput out)
                throws GRS2RecordSerializationException
Sends the state and payload of the Record to a remote requester. After writing the internally managed information, a call to extendSend(DataOutput) is made, and for every Field hosted, a call to Field.send(DataOutput) is made

Parameters:
out - the stream to send to
Throws:
GRS2RecordSerializationException - there was a problem serializing the information

sendToXML

public final org.w3c.dom.Element sendToXML(org.w3c.dom.Document doc)
                                    throws GRS2RecordSerializationException
Throws:
GRS2RecordSerializationException

inflate

public final void inflate(java.io.DataInput in)
                   throws GRS2RecordSerializationException
Inflate the state and data of the implementor as was previously deflated using IPumpable.deflate(DataOutput) Similar as calling inflate(DataInput, boolean) with a reset parameter of false

Specified by:
inflate in interface IPumpable
Parameters:
in - the stream to inflate from
Throws:
GRS2RecordSerializationException - the inflate could not be completed
See Also:
inflate(DataInput, boolean), IPumpable.inflate(java.io.DataInput)

inflate

public final void inflate(java.io.DataInput in,
                          boolean reset)
                   throws GRS2RecordSerializationException
Inflate the state and data of the implementor as was previously deflated using IPumpable.deflate(DataOutput) Inflates the Record from the provided stream as it was previously deflated using the method deflate(DataOutput). After deflating the internally kept information, the stream is passed to extendDeflate(DataOutput) and then the serializations of the hosted Fields are read by the respective Field.inflate(DataInput, boolean)

Specified by:
inflate in interface IPumpable
Parameters:
in - the stream to inflate from
reset - whether or not the inflated information should be reset to drop any information previously stored concerning transfers performed by the Record
Throws:
GRS2RecordSerializationException - there was a problem deserializing the information

receive

public final void receive(java.io.DataInput in)
                   throws GRS2RecordSerializationException
Receives the state and payload of the Record from a remote sender. After reading the internally managed information, a call to extendReceive(DataInput) is made, and for every Field hosted, a call to Field.receive(DataInput) is made

Parameters:
in - the stream to receive from
Throws:
GRS2RecordSerializationException - there was a problem deserializing the information

makeLocal

public final void makeLocal()
Called by RecordWriter.importRecord(T). External usage is unnecessary and discouraged.

Resets all internally kept information concerning transfers performed by the Record and makes it behave as it were local. For all Fields, Field.makeLocal() is invoked, therefore if partial transfers are involved Field.makeAvailable() should be invoked beforehand in case the full payload is needed.

See Also:
Field.makeLocal()

extendSend

public abstract void extendSend(java.io.DataOutput out)
                         throws GRS2RecordSerializationException
The method all Record implementations should implement to add any information they keep during transfer

Parameters:
out - the stream to transfer through
Throws:
GRS2RecordSerializationException - Information serialization problem

extendSendToXML

public abstract void extendSendToXML(org.w3c.dom.Document doc,
                                     org.w3c.dom.Element element)
                              throws GRS2RecordSerializationException
Throws:
GRS2RecordSerializationException

extendReceiveFromXML

public abstract void extendReceiveFromXML(org.w3c.dom.Element element)
                                   throws GRS2RecordSerializationException
Throws:
GRS2RecordSerializationException

extendReceive

public abstract void extendReceive(java.io.DataInput in)
                            throws GRS2RecordSerializationException
The method all Record implementations should implement to read any information they send during transfer

Parameters:
in - the stream to read from
Throws:
GRS2RecordSerializationException - Information deserialization error

extendDeflate

public abstract void extendDeflate(java.io.DataOutput out)
                            throws GRS2RecordSerializationException
The method all Record implementations should implement to add any information they keep during deflate

Parameters:
out - the stream to deflate to
Throws:
GRS2RecordSerializationException - Information serialization problem

extendInflate

public abstract void extendInflate(java.io.DataInput in,
                                   boolean reset)
                            throws GRS2RecordSerializationException
The method all Record implementations should implement to read any information they deflated

Parameters:
in - the stream to inflate from
reset - whether or not the inflated information should be reset to drop any information previously stored concerning transfers performed by the Field
Throws:
GRS2RecordSerializationException - Information deserialization error

dispose

public void dispose()
Disposes all internally kept state, calls extendDispose() and then for every hosted Field, calls Field.dispose()


extendDispose

public abstract void extendDispose()
Method to be implemented by Record extenders to dispose any internally kept state


requestPartial

public void requestPartial(IBuffer.TransportOverride override,
                           int fieldIndex)
                    throws GRS2ProxyMirrorException
if the associated IBuffer has a IMirror set, then the IMirror#requestPartial(long, int, TransportOverride, Object) method is used to request additional payload for the specific Field of the Record. Requests for more of partial content can only be issued against Fields of a Record and not for Records themselves

Parameters:
override - the IBuffer.TransportOverride directive
fieldIndex - the field index to request data for
Throws:
GRS2ProxyMirrorException - The state of the IMirror does not allow for this operation to be completed

makeAvailable

public void makeAvailable()
                   throws GRS2RecordDefinitionException,
                          GRS2ProxyMirrorException,
                          GRS2BufferException
For all hosted Fields, the method makeAvailable(int)

Throws:
GRS2RecordDefinitionException - the record definition could not be retrieved
GRS2ProxyMirrorException - There was an error during the mirroring process
GRS2BufferException - the IBuffer state does not allow for this operation to be completed

makeAvailable

public void makeAvailable(java.lang.String fieldName)
                   throws GRS2RecordDefinitionException,
                          GRS2ProxyMirrorException,
                          GRS2BufferException
For the specified Field with the set name, the method Record#makeAvailable(TransportOverride, int) with a value of IBuffer.TransportOverride.Override

Parameters:
fieldName - the name of the field to make available
Throws:
GRS2RecordDefinitionException - the record definition could not be retrieved
GRS2ProxyMirrorException - There was an error during the mirroring process
GRS2BufferException - the IBuffer state does not allow for this operation to be completed

makeAvailable

public void makeAvailable(int fieldIndex)
                   throws GRS2RecordDefinitionException,
                          GRS2ProxyMirrorException,
                          GRS2BufferException
For the specified Field with the set index, the method Record#makeAvailable(TransportOverride, int) with a value of IBuffer.TransportOverride.Override

Parameters:
fieldIndex - the index of the field
Throws:
GRS2RecordDefinitionException - the record definition could not be retrieved
GRS2ProxyMirrorException - There was an error during the mirroring process
GRS2BufferException - the IBuffer state does not allow for this operation to be completed

toXML

public final org.w3c.dom.Element toXML(org.w3c.dom.Document doc)
                                throws GRS2RecordSerializationException
Specified by:
toXML in interface IPumpable
Throws:
GRS2RecordSerializationException

receiveFromXML

public final void receiveFromXML(org.w3c.dom.Element element)
                          throws GRS2RecordSerializationException
Throws:
GRS2RecordSerializationException

fromXML

public final void fromXML(org.w3c.dom.Element element)
                   throws GRS2RecordSerializationException
Specified by:
fromXML in interface IPumpable
Throws:
GRS2RecordSerializationException