fulmine.protocol.wire
Interface IWireState

All Known Subinterfaces:

IComponent, IContainer, IContainerDefinitionField, IField

All Known Implementing Classes:

AbstractComponent, AbstractContainer, AbstractDynamicContainer, AbstractEventProcessingContainer, AbstractField, ActiveAsymmetricEventProcessor, AsymmetricEventProcessor, BasicContainer, BooleanField, ContainerDefinitionField, DescriptorField, DoubleField, EventSource, FloatField, ImageEvent, IntegerField, LongField, Record, StringField, SystemEventSource

public interface IWireState

An object that can read and write its internal state into a 'wire' format suitable for transporting to and from foreign hosts. The wire format is the fulmine delta (FD) protocol format.

When transmitting an IWireState from a host, the object writes its state (including its identity) to byte buffers that are sent to the network transport layer as an FD frame. On the receiving host, the FD frame is received, the byte buffers are reconstructed from the network transport layer and the identity is extracted. An IWireState object with the same identity is located and the bytes are given to this object to process. This object updates its internal state from the received byte buffers.

The mechanism for how the receiving host locates an IWireState object with the same identity is an implementation specific detail.

Author:

Ramon Servadei

Method Summary

void	readState(IOperationScope scope, byte[] buffer, int start, int numberOfBytes) Update this object's internal state from the fulmine delta (FD) wire format state encapsulated in the byte buffer.
void	writeState(IOperationScope scope, IWireIdentity wireId, byte[][] headerBuffer, int[] headerBufferPosition, byte[][] dataBuffer, int[] dataBufferPosition, boolean completeState) Write the state of this object in fulmine delta (FD) wire format to the byte buffers.

Method Detail

writeState

void writeState(IOperationScope scope,
                IWireIdentity wireId,
                byte[][] headerBuffer,
                int[] headerBufferPosition,
                byte[][] dataBuffer,
                int[] dataBufferPosition,
                boolean completeState)

Write the state of this object in fulmine delta (FD) wire format to the byte buffers. This operation can write the entire state or just changes.

The object fields are written into headerBuffer[0] starting at headerBufferPosition[0]. The fields are written in 'component spec' format. The diagram below illustrates the IWF component spec for a single component:

 -------------------------------------------------------
 |   1 byte        |   component bytes   |   data bytes    |
 -------------------------------------------------------
 | 7 6 5 4 3 2 1 0 |                 |                 |
 -------------------------------------------------------
 |   fbc  |   dbc  |     component       |  data position  |
 -------------------------------------------------------
 

• fbc - the number of bytes for the component portion
• dbc - the number of bytes for the data position portion
• component - the bytes for the component. This is the wire format for the component and will differ depending on the component type.
• data position - the position in the data buffer where the data is written

An SWF component spec is slightly different:

 -------------------------------------------------------
 | 1 byte | 1 byte |   component bytes   |   data bytes    |
 -------------------------------------------------------
 |   fbc  |   dbc  |     component       |  data position  |
 -------------------------------------------------------
 

The data is written into dataBuffer[0] starting at dataBufferPosition[0].

Parameters:

scope - the scope of the write state operation

wireId - the wire identity, expresses if this is an IWF or SWF component spec

headerBuffer - headerBuffer[0] holds the header buffer to write the component spec that describes the object's fields and their corresponding data positions in the dataBuffer

headerBufferPosition - headerBufferPosition[0] holds the current position in the headerBuffer[0]

dataBuffer - dataBuffer[0] holds the data buffer that component data is written to

dataBufferPosition - dataBufferPosition[0] holds the current position in the dataBuffer[0]

completeState - whether to write the complete state or only changes

readState

void readState(IOperationScope scope,
               byte[] buffer,
               int start,
               int numberOfBytes)

Update this object's internal state from the fulmine delta (FD) wire format state encapsulated in the byte buffer.

The wire format state includes the fields of the object that have changed. The logic to read the component state should be delegated to the individual component.

Parameters:

scope - the scope of the read state operation

buffer - the byte buffer that holds the contiguous wire format state to read, at some position

start - where the wire format state begins in the byte buffer

numberOfBytes - the number of bytes in the byte buffer to read the wire format state