gr.uoa.di.madgik.grs.record

Class Record

java.lang.Object

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

All Implemented Interfaces:

IPumpable, Serializable

Direct Known Subclasses:

GenericRecord

public abstract class Record
extends Object
implements IPumpable, Serializable

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

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Record()

Method Summary

Modifier and Type	Method and Description
void	bind(IBuffer buffer) Binds the Record to the provided IBuffer.
void	deflate(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(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(DataInput in, boolean reset) The method all Record implementations should implement to read any information they deflated
protected abstract void	extendMakeLocal() The method all Record implementations should implement to reset additional information they keep concerning transfers performed
abstract void	extendReceive(DataInput in) The method all Record implementations should implement to read any information they send during transfer
abstract void	extendSend(DataOutput out) The method all Record implementations should implement to add any information they keep during transfer
void	fromXML(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(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(DataInput in) Inflate the state and data of the implementor as was previously deflated using IPumpable.deflate(DataOutput)
void	inflate(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(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(DataInput in) Receives the state and payload of the Record from a remote sender.
void	receiveFromXML(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(DataOutput out) Sends the state and payload of the Record to a remote requester.
Element	sendToXML(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	setID(long id)
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.
Element	toXML(Document doc)
void	unbind() Unbinds the Record from the IBuffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, 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

setID

public void setID(long 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(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(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(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 Element sendToXML(Document doc)
                  throws GRS2RecordSerializationException

Throws:

GRS2RecordSerializationException

inflate

public final void inflate(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(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(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(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

extendReceive

public abstract void extendReceive(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(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(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

extendMakeLocal

protected abstract void extendMakeLocal()

The method all Record implementations should implement to reset additional information they keep concerning transfers performed

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(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 Element toXML(Document doc)
                    throws GRS2RecordSerializationException

Specified by:

toXML in interface IPumpable

Throws:

GRS2RecordSerializationException

receiveFromXML

public void receiveFromXML(Element element)
                    throws GRS2RecordSerializationException

Throws:

GRS2RecordSerializationException

fromXML

public final void fromXML(Element element)
                   throws GRS2RecordSerializationException

Specified by:

fromXML in interface IPumpable

Throws:

GRS2RecordSerializationException