hypercast
Class OL_Message

java.lang.Object
  |
  +--hypercast.OL_Message
All Implemented Interfaces:
I_Message, I_OverlayMessage

public class OL_Message
extends java.lang.Object
implements I_OverlayMessage, I_Message

This class implements the I_OverlayMessage interface and defines the messages exchanged between socket adapters of overlay sockets. It is used by applications to send data. It is also used to send overlay messages for monitoring and control objectives. This class is not used in exchanging protocol messages via node adapters. An overlay message has the following format: ---------------------------- ------------- | Overlay | Extension | ... | Extension | |message header| | | | ---------------------------- ------------- Here, the format of overlay message header is: (Overlay Message Length and LA Size are in units of bytes) ------------------------------------------------------------- |Version| DMode |Traffic Class| Flow Label | | 4 bits| 4 bits| 8 bits | 16 bits | ------------------------------------------------------------- | Overlay Message Length | Hop Limit | | 16 bits | 16 bits | -------------------------------------------------------------------- |Extension Type | LA Size | Source Logical Address / | 8 bits | 8 bits | variable / --------------------------------------------------------------------------- / Previous Hop Logical Address / Destination Logical Address / / variable length / (only if DMode is Unicast, variable) / --------------------------------------------------------------------------- Each extension has the following format: (in bytes) ---------------------------------------------------------------------- | Next Ext. Type | Extension Length | Extension Specific Information | | 8 bits | 16 bits | > 0 bytes | ---------------------------------------------------------------------- The extension types are defined in class Extension. @see Extension 1. There is only one extension with type Payload (RAW_DATA). It carries the application payload. It does not have to be the last extension. 2. In an overlay message, each extension, except the Payload extension, contains plain text information. (TODO: I'm not certain that this is true) 3. In general, there is no assumption on the order of extensions.


Field Summary
static byte DELIVERY_MODE_FLOOD
           
static byte DELIVERY_MODE_INVALID
           
static byte DELIVERY_MODE_MULTICAST
           
static byte DELIVERY_MODE_UNICAST
           
 
Fields inherited from interface hypercast.I_OverlayMessage
DELDUPS, E2EACK, H2HACK, INCAST, INORDER, NAMING, NOSERVICE, SYNC
 
Constructor Summary
OL_Message(hypercast.OL_Message orig_msg)
          Create an OL_Message by cloning another OL_Message instance.
OL_Message(short hopLimit, hypercast.I_LogicalAddress sourceAddress)
          Create an empty OL_Message with specified hopLimit and source logical address.
OL_Message(short hopLimit, hypercast.I_LogicalAddress sourceAddress, hypercast.KeyVault kv)
          Create an empty OL_Message with specified hopLimit, source logical address and key vault.
 
Method Summary
 void addExtension(hypercast.Extension extension)
          Add a extension to the Overlay application message.
 short decrementHopLimit()
          Decrements the hop limit by one and returns the decremented value.
 byte getDeliveryMode()
          Returns the delivery mode of the message
 hypercast.I_LogicalAddress getDestinationAddress()
          Gets the destination logical address in this message
 java.util.Vector getExtension()
          Gets the extension store (vector) in this message
 hypercast.Extension getExtension(int index)
          Gets the extension at specified position in the extension store (vector) of this message.
 hypercast.Extension getFirstExtensionByType(byte type)
          Returns the first extension with specified extension type.
 byte getFlowLabel()
          Accesses the flow label.
 short getHopLimit()
          Returns the maximum number of hops that this message may take in the network.
 byte[] getMessageID()
          Deprecated. use getMessageIdentifier
 byte[] getMessageIdentifier()
          Returns the message identifier carried by this message.
 byte[] getPayload()
          Returns the plaintext application payload.
 int getPayloadLength()
          Returns the length of application payload.
 hypercast.I_LogicalAddress getPrevhopAddress()
          Deprecated. name has changed from Prevhop Address to Previous Hop Address, use getPreviousHopAddress
 hypercast.I_LogicalAddress getPreviousHopAddress()
          Gets the previous hop logical address in this message
 hypercast.I_LogicalAddress getRoutingAddress()
          Deprecated. name has changed: Routing Address to Destination Address, use getDestinationAddress
 long getSequenceNumber()
          Returns the sequence number carried by this message.
 short getServiceIdentifier()
          Returns the service number carried by this message.
 short getServiceNumber()
          Deprecated. use getServiceIdentifier
 int getSize()
           
 hypercast.I_LogicalAddress getSourceAddress()
           
 hypercast.I_LogicalAddress getSrcAddress()
          Deprecated. name has changed from Src Address to Source Address, use getSourceAddress
 byte[] getStreamID()
          Gets the stream ID of the message.
 int getStreamIdentifier()
          Returns the stream identifier carried by this message.
 byte getTrafficClass()
          Returns the traffice class of the message
 byte getVersion()
          Returns the version of the message.
static boolean isValidDeliveryMode(byte mode)
          Validates the value of a delivery mode.
static hypercast.OL_Message restoreMessage(byte[] recvbuff, int[] validBytesStart, int validBytesEnd, hypercast.I_Node node, hypercast.KeyVault kv)
          Restore an OL_Message from an byte array.
 void setDeliveryMode(byte deliveryMode)
          Sets the delivery mode in this message
 void setDestinationAddress(hypercast.I_LogicalAddress destinationAddress)
          Sets the destination address in this message
 void setExtension(int index, hypercast.Extension e)
          Sets the extension at specified position in the extension store (vector) of this message.
 void setFirstExtensionByType(int type, hypercast.Extension ee)
          Sets the first extension with specified extension type.
 void setHopLimit(short hopLimit)
          Sets the hop limit of this message.
 void setKeyVault(hypercast.KeyVault kv)
          Sets key vault instance in this message.
 void setMsgIdentifier(int msgID)
          Sets the message identifier in this message if the message is an enhanced service message.
 void setPayload(byte[] newPayload)
          Sets the payload.
 void setPrevhopAddress(hypercast.I_LogicalAddress previousHopAddress)
          Deprecated. name has changed from Prevhop Address to Previous Hop Address, use setPreviousHopAddress
 void setPreviousHopAddress(hypercast.I_LogicalAddress previousHopAddress)
          Sets the previous hop address in this message
 void setRoutingAddress(hypercast.I_LogicalAddress destinationAddress)
          Deprecated. name has changed: Routing Address to Destination Address, use setDestinationAddress
 void setSequenceNumber(long sequenceNum)
          Sets the sequence number in this message if the message is an stream-oriented message.
 void setServiceIdentifier(short serviceID)
          Sets the service number in the enhanced service message.
 void setSourceAddress(hypercast.I_LogicalAddress sourceAddress)
          Sets the logical address in this message
 void setSrcAddress(hypercast.I_LogicalAddress rtaddress)
          Deprecated. name has changed from Src Address to Source Address, use setSourceAddress
 void setStreamIdentifier(int streamID)
          Sets the stream identifier in this message if the message is an enhanced service message.
 void setTrafficClass(byte trafficClass)
          Sets the traffic class of the message.
 byte[] toByteArray()
          Convert this message into a byte array.
 java.lang.String toString()
          Converts the overaly message object to String representation.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DELIVERY_MODE_INVALID

public static final byte DELIVERY_MODE_INVALID
See Also:
Constant Field Values

DELIVERY_MODE_MULTICAST

public static final byte DELIVERY_MODE_MULTICAST
See Also:
Constant Field Values

DELIVERY_MODE_FLOOD

public static final byte DELIVERY_MODE_FLOOD
See Also:
Constant Field Values

DELIVERY_MODE_UNICAST

public static final byte DELIVERY_MODE_UNICAST
See Also:
Constant Field Values
Constructor Detail

OL_Message

public OL_Message(short hopLimit,
                  hypercast.I_LogicalAddress sourceAddress)
Create an empty OL_Message with specified hopLimit and source logical address.

Parameters:
hopLimit - Maximum number of hops that message will be allowed to have in network
sourceAddress - Logical address that will be used as the source of the message

OL_Message

public OL_Message(hypercast.OL_Message orig_msg)
Create an OL_Message by cloning another OL_Message instance.


OL_Message

public OL_Message(short hopLimit,
                  hypercast.I_LogicalAddress sourceAddress,
                  hypercast.KeyVault kv)
Create an empty OL_Message with specified hopLimit, source logical address and key vault.

Parameters:
hopLimit - Maximum number of hops that message will be allowed to have in network
sourceAddress - Logical address that will be used as the source of the message
kv - an KeyVault instance for security computation
Method Detail

restoreMessage

public static hypercast.OL_Message restoreMessage(byte[] recvbuff,
                                                  int[] validBytesStart,
                                                  int validBytesEnd,
                                                  hypercast.I_Node node,
                                                  hypercast.KeyVault kv)
Restore an OL_Message from an byte array. Actually, this code validates that a complete message is inside the buffer and then calls the constructor to do the actual reconstruction.

Parameters:
recvbuff - the byte array buffer
validBytesStart - start of valid section of the array, this variable is essentially a pointer to an int, the caller of this method expects that the value will be updated to reflect the bytes of the buffer consumed by this method, i.e. on return the value of this variable should be set to the next valid byte after the message that has been restored.
validBytesEnd - end of valid section of the array (actually, 1 beyond last valid byte.)
node - an I_Node object which is used to get LogicalAddress size
kv - an KeyVault instance for security computation
Returns:
an object of OL_Message
Throws:
throw - IllegalArgumentException for invalid version and deliveryMode

toByteArray

public byte[] toByteArray()
Convert this message into a byte array.

Specified by:
toByteArray in interface I_Message
Returns:
a byte array representation of this message
Throws:
java.lang.IllegalStateException - if souce address or destination address are null

isValidDeliveryMode

public static boolean isValidDeliveryMode(byte mode)
Validates the value of a delivery mode.

Returns:
true if the value of mode is one of the supported modes of delivery, false otherwise

getSize

public int getSize()

getHopLimit

public short getHopLimit()
Description copied from interface: I_OverlayMessage
Returns the maximum number of hops that this message may take in the network. If called on a message that has been received from some other node this value is the original hop limit minus the number of hops that the message has already taken.

Specified by:
getHopLimit in interface I_OverlayMessage
Returns:
The hop limit of the message (unsigned 16 bit quantity).

decrementHopLimit

public short decrementHopLimit()
Decrements the hop limit by one and returns the decremented value. To perform this operation, Java 32 bit integers are used internally when operating on the 16-bit unsigned quantity because Java does not support an unsigned 16-bit quantity.

Returns:
The hop limit of the message after decrementing it by one (unsigned 16 bit quantity). Note that any value other than zero is a positive value because this value is not interpreted as a signed quantity. Do compare this value to zero, e.g. if (msg.decrementHopLimit() != 0). Do not use greater than or less than in comparisons, e.g. if (msg.decrementHopLimit() > 0). The latter comparison will fail when the hop limit is large because a large hop limit is represented as a negative Java short.
Throws:
HyperCastWarningRuntimeException - if the current hop limit is zero

setHopLimit

public void setHopLimit(short hopLimit)
Sets the hop limit of this message. Application can not call this function to set hop limit of message directly. This function can ONLY be called by a OL_Socket. All values of a short are valid. The short is interpreted as an unsigned 16 bit quantity, e.g. a value of -1 (0xFFFF) means a hop limit of (2^16)-1.

Specified by:
setHopLimit in interface I_OverlayMessage

getPayloadLength

public int getPayloadLength()
Returns the length of application payload. It is the length of the application data (byte array) in the extension with type RAW_DATA.

Specified by:
getPayloadLength in interface I_OverlayMessage

getPayload

public byte[] getPayload()
Returns the plaintext application payload.

Specified by:
getPayload in interface I_OverlayMessage

setPayload

public void setPayload(byte[] newPayload)
Sets the payload.


getVersion

public byte getVersion()
Returns the version of the message.


getDeliveryMode

public byte getDeliveryMode()
Returns the delivery mode of the message


setDeliveryMode

public void setDeliveryMode(byte deliveryMode)
Sets the delivery mode in this message

Parameters:
deliveryMode - delivery mode
Throws:
throw - IllegalArgumentException for invalid delivery mode

getTrafficClass

public byte getTrafficClass()
Returns the traffice class of the message

Specified by:
getTrafficClass in interface I_OverlayMessage

setTrafficClass

public void setTrafficClass(byte trafficClass)
Sets the traffic class of the message.

Specified by:
setTrafficClass in interface I_OverlayMessage

getMessageID

public byte[] getMessageID()
Deprecated. use getMessageIdentifier

Returns the unique identifier of this message.

Specified by:
getMessageID in interface I_OverlayMessage

getServiceNumber

public short getServiceNumber()
Deprecated. use getServiceIdentifier

Returns the service number carried by this message.

Specified by:
getServiceNumber in interface I_OverlayMessage

getServiceIdentifier

public short getServiceIdentifier()
Returns the service number carried by this message.

Specified by:
getServiceIdentifier in interface I_OverlayMessage
Throws:
HyperCastWarningRuntimeException - if the message is not an enhanced service message.

setServiceIdentifier

public void setServiceIdentifier(short serviceID)
Sets the service number in the enhanced service message.

Specified by:
setServiceIdentifier in interface I_OverlayMessage
Parameters:
serviceID - service identifier
Throws:
HyperCastWarningRuntimeException - if the message is not an enhanced service message , or setting new service identifier will change the message type.

getStreamID

public byte[] getStreamID()
Deprecated. use getStreamIdentifier

Description copied from interface: I_OverlayMessage
Gets the stream ID of the message. This method is useful only when messageStore is used for the transmission of application messages. If there is no stream id associated with this message, null is returned.

Specified by:
getStreamID in interface I_OverlayMessage
Returns:
the stream identifier carried by this message.

getStreamIdentifier

public int getStreamIdentifier()
Returns the stream identifier carried by this message. It returns -1 if the message is not a enhanced service message.

Specified by:
getStreamIdentifier in interface I_OverlayMessage
Throws:
HyperCastWarningRuntimeException - if the message is not a stream oriented message.

setStreamIdentifier

public void setStreamIdentifier(int streamID)
Sets the stream identifier in this message if the message is an enhanced service message.

Specified by:
setStreamIdentifier in interface I_OverlayMessage
Parameters:
streamID - stream identifier in byte array format
Throws:
HyperCastWarningRuntimeException - if the message is not a stream oriented message.

getSequenceNumber

public long getSequenceNumber()
Returns the sequence number carried by this message.

Specified by:
getSequenceNumber in interface I_OverlayMessage
Throws:
HyperCastWarningRuntimeException - if the message is not a stream oriented message.

setSequenceNumber

public void setSequenceNumber(long sequenceNum)
Sets the sequence number in this message if the message is an stream-oriented message.

Specified by:
setSequenceNumber in interface I_OverlayMessage
Parameters:
sequenceNum - the sequence number
Throws:
HyperCastWarningRuntimeException - if the message is not a stream oriented message.

getMessageIdentifier

public byte[] getMessageIdentifier()
Returns the message identifier carried by this message. Message identifier is defined only when the message has a message store (fsm/enhanced service) extension.

Specified by:
getMessageIdentifier in interface I_OverlayMessage
Returns:
the message identifier carried by this message. It returns -1 if the message is not a enhanced service message.
Throws:
HyperCastWarningRuntimeException - if the message is not a messagestroe oriented message.

setMsgIdentifier

public void setMsgIdentifier(int msgID)
Sets the message identifier in this message if the message is an enhanced service message.

Specified by:
setMsgIdentifier in interface I_OverlayMessage
Parameters:
msgID - the message identifier
Throws:
HyperCastWarningRuntimeException - if the message is not a messagestroe oriented message.

addExtension

public void addExtension(hypercast.Extension extension)
Add a extension to the Overlay application message.

Parameters:
extension - the extension to be added into extension vector.
Throws:
throw - IllegalArgumentException if the type of the extension is not supported.

getFirstExtensionByType

public hypercast.Extension getFirstExtensionByType(byte type)
Returns the first extension with specified extension type.


setFirstExtensionByType

public void setFirstExtensionByType(int type,
                                    hypercast.Extension ee)
Sets the first extension with specified extension type.


getExtension

public java.util.Vector getExtension()
Gets the extension store (vector) in this message


getExtension

public hypercast.Extension getExtension(int index)
Gets the extension at specified position in the extension store (vector) of this message.


setExtension

public void setExtension(int index,
                         hypercast.Extension e)
Sets the extension at specified position in the extension store (vector) of this message.


getFlowLabel

public byte getFlowLabel()
Accesses the flow label. NB The flow label is not an unused field in this version of HyperCast.

Returns:
the flow label of the message.

getSrcAddress

public hypercast.I_LogicalAddress getSrcAddress()
Deprecated. name has changed from Src Address to Source Address, use getSourceAddress

Gets the source logical address in this message

Specified by:
getSrcAddress in interface I_OverlayMessage

getSourceAddress

public hypercast.I_LogicalAddress getSourceAddress()
Specified by:
getSourceAddress in interface I_OverlayMessage
Returns:
the source logical address of this message.

setSrcAddress

public void setSrcAddress(hypercast.I_LogicalAddress rtaddress)
Deprecated. name has changed from Src Address to Source Address, use setSourceAddress

Sets the logical address in this message


setSourceAddress

public void setSourceAddress(hypercast.I_LogicalAddress sourceAddress)
Sets the logical address in this message


getRoutingAddress

public hypercast.I_LogicalAddress getRoutingAddress()
Deprecated. name has changed: Routing Address to Destination Address, use getDestinationAddress

Gets the destination logical address in this message


getDestinationAddress

public hypercast.I_LogicalAddress getDestinationAddress()
Gets the destination logical address in this message


setRoutingAddress

public void setRoutingAddress(hypercast.I_LogicalAddress destinationAddress)
Deprecated. name has changed: Routing Address to Destination Address, use setDestinationAddress

Sets the destination address in this message


setDestinationAddress

public void setDestinationAddress(hypercast.I_LogicalAddress destinationAddress)
Sets the destination address in this message


getPrevhopAddress

public hypercast.I_LogicalAddress getPrevhopAddress()
Deprecated. name has changed from Prevhop Address to Previous Hop Address, use getPreviousHopAddress

Gets the previous hop logical address in this message


getPreviousHopAddress

public hypercast.I_LogicalAddress getPreviousHopAddress()
Gets the previous hop logical address in this message


setPrevhopAddress

public void setPrevhopAddress(hypercast.I_LogicalAddress previousHopAddress)
Deprecated. name has changed from Prevhop Address to Previous Hop Address, use setPreviousHopAddress

Sets the previous hop address in this message


setPreviousHopAddress

public void setPreviousHopAddress(hypercast.I_LogicalAddress previousHopAddress)
Sets the previous hop address in this message


setKeyVault

public void setKeyVault(hypercast.KeyVault kv)
Sets key vault instance in this message. It also creates the security auxialiary computation object in this message.


toString

public java.lang.String toString()
Converts the overaly message object to String representation. TODO: is this needed? if so, is it only for debugging? statistics?

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the OL_Message object