hypercast
Class OL_Socket

java.lang.Object
  |
  +--hypercast.OL_Socket
All Implemented Interfaces:
I_AdapterCallback, I_OverlaySocket, I_ReceiveCallback, I_Stats

public class OL_Socket
extends java.lang.Object
implements I_OverlaySocket, I_AdapterCallback, I_ReceiveCallback

This class implements all the functions of an overlay socket. It contains an overlay node that maintains the overlay topology. A forward engine is runnig inside this class for sending and receiving application messages. This class also provides interfaces for applications to handling data sending and receiving.


Field Summary
 
Fields inherited from interface hypercast.I_OverlaySocket
HOP_LIMIT_MAXIMUM
 
Constructor Summary
OL_Socket(hypercast.HyperCastConfig config, hypercast.I_ReceiveCallback callback)
          Create an overlay socket with a HyperCastConfig object and a Callback interface.
OL_Socket(hypercast.HyperCastConfig config, hypercast.I_ReceiveCallback callback, hypercast.NotificationHandler notificationHandler)
          Create an overlay socket with a HyperCastConfig object, a callback object and a notification handler.
OL_Socket(hypercast.HyperCastConfig config, hypercast.I_ReceiveCallback callback, hypercast.NotificationHandler notificationHandler_parameter, hypercast.I_InterceptionCallback interceptionCallback)
          Create an overlay socket with a HyperCastConfig object, a callback object and a notification handler.
 
Method Summary
 void appmsgArrived(hypercast.I_OverlayMessage message, hypercast.I_ReceiveCallback callback)
          Passes the message to the application via the callback.
 void closeSocket()
          This method permanently closes the socket.
 hypercast.I_LogicalAddress createLogicalAddress(byte[] encodedLogicalAddress, int offset)
          Creates an I_LogicalAddress from a bytes array
 hypercast.I_LogicalAddress createLogicalAddress(java.lang.String logicalAddressString)
          Creates a logical address object from a String.
 hypercast.I_OverlayMessage createMessage()
          Same as calling createMessage(byte []) with parameter of null.
 hypercast.I_OverlayMessage createMessage(byte[] payload)
          Creates an overlay message with an application payload extension.
 hypercast.I_OverlayMessage createMessage(byte[] payload, byte[] streamid)
          Creates a message with specified stream id.
 hypercast.I_OverlayMessage createMessage(byte[] payload, int length)
          Deprecated. The length parameter is redundant.
 hypercast.I_OverlayMessage createMessage(byte[] payload, int length, byte[] streamid)
          Deprecated. The length parameter is redundant.
 hypercast.I_OverlayMessage createMessage(byte[] payload, int length, int servicenumber)
          Deprecated. The length parameter is redundant.
 hypercast.I_OverlayMessage createMessage(byte[] payload, short serviceNumber)
          Create an OL_Message containing an extension that contains an appliction payload extension and a message store extension.
 short generateMsgIdentifier()
          Returns a message identifier.
 short generateStreamIdentifier()
          Returns a stream identifier.
 hypercast.I_LogicalAddress[] getChildren(hypercast.I_LogicalAddress root)
          Returns an array consisting of the logical addresses of the children of this node.
 short getHopLimit()
          Get the default hop limit for multicast packets sent out on the OL_Socket.
 hypercast.I_LogicalAddress getLogicalAddress()
          Returns the node's logical address
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
          Implementation of I_OverlaySocket.getLogicalAddress(String).
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Implementation of I_OverlaySocket.getLogicalAddress(String).
 int getLogicalAddressByNameNonBlocking(java.lang.String name)
          Implementation of I_OverlaySocket.getLogicalAddressNonBlocking(String).
 int getLogicalAddressByNameNonBlocking(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Implementation of I_OverlaySocket.getLogicalAddressNonBlocking(String).
 java.lang.String[] getNames()
          Implementation of I_OverlaySocket.getName().
 java.lang.String[] getNames(hypercast.I_LogicalAddress logicalAddress)
          Implementation of I_OverlaySocket.getName(I_LogicalAddress).
 java.lang.String[] getNames(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short maxHopCount, short minHopCount)
          Implementation of I_OverlaySocket.getName(I_LogicalAddress,boolean,long,boolean,boolean,int,int,short).
 int getNamesNonBlocking(hypercast.I_LogicalAddress address)
          Implementation of I_OverlaySocket.getNameNonBlocking(I_LogicalAddress).
 int getNamesNonBlocking(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Implementation of I_OverlaySocket.getNameNonBlocking(I_LogicalAddress).
 hypercast.I_LogicalAddress[] getNeighbors()
          Returns an array consisting of the logical addresses of this node's neighbors.
 hypercast.I_LogicalAddress getParent(hypercast.I_LogicalAddress root)
          Returns this node's parent with respect to a tree starting at "root".
 org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Dynamically generates a subtree of the Readable Schema rooted at the path specified by the xpath.
 int getSoTimeout()
          Retrive setting for SO_TIMEOUT.
 org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Gets statistics information from an object which implements this interface.
 java.lang.String getStatsName()
          Gets the element name of this I_Stats instance.
 hypercast.StreamManager getStreamManager()
           
 byte[] getUniqueIdentifier()
          Returns the unique identifier for this node.
 org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Dynamically generates a subtree of the Writable Schema rooted at the path specified by the xpath.
 void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
          Implementation of I_OverlaySocket.installTrustedNamingCertificate().
 void joinOverlay()
          Implements the operation of joining an overlay network.
 void leaveOverlay()
          Leaves a multicast group, stopping all threads started by joinOverlay() in reverse order.
 void messageArrivedFromAdapter(hypercast.I_Message msg)
          This method implements the heart of the "Forwarding Engine." The bulk of the remaining portions of the forwarding engine can be found in the methods with the prefix "forward"
 void namingLogicalAddressChange()
          Implementation of I_OverlaySocket.namingLogicalAddressChange().
 hypercast.I_OverlayMessage receive()
          Receives an overlay application message from this socket.
 void ReceiveCallback(hypercast.I_OverlayMessage message)
          TODO: document me!
 hypercast.I_Message restoreMessage(byte[] recvbuff, int[] validBytesStart, int validBytesEnd)
          Creates an I_Message from a byte array.
 void sendFlood(hypercast.I_OverlayMessage message)
          Floods a message to all nodes.
 void sendIncast(hypercast.I_OverlayMessage message, byte[] messageid, hypercast.I_LogicalAddress root)
          Send Incast message to root node.
 void sendToAll(hypercast.I_OverlayMessage message)
          Sends a multicast overlay message to all nodes in the multicast group from this socket; the sender receives a copy as well.
 void sendToAllNeighbors(hypercast.I_OverlayMessage message)
          Sends message to all the neighbors.
 void sendToChildren(hypercast.I_OverlayMessage message, hypercast.I_LogicalAddress root)
          Sends message to all the children nodes from this socket.
 void sendToNode(hypercast.I_OverlayMessage message, hypercast.I_LogicalAddress destinationLogicalAddress)
          Sends a message to a specified node.
 void sendToParent(hypercast.I_OverlayMessage message, hypercast.I_LogicalAddress root)
          Sends a message to parent.
 void setHopLimit(short hopLimit)
          Set the default hop limit for multicast packets sent out on this socket.
 void setLogicalAddress(hypercast.I_LogicalAddress logicalAddress)
          Sets the logical address to specified one.
 void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          Implementation of I_OverlaySocket.setName().
 void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey, java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
          Assigns the specified name to the specified logical address using the specified private key (that matches the public key in the specified certificate) to create a digital signature for the new binding.
 void setName(java.lang.String name)
          Implementation of I_OverlaySocket.setName().
 void setName(java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
          Assigns the specified name to the specified logical address.
 void setSoTimeout(int timeout)
          Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
 org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath, org.w3c.dom.Element newValue)
          Sets statistics information for an object which implements this interface.
 void setStatsName(java.lang.String name)
          Assigns a name to this I_Stats instance.
 void timerExpired(java.lang.Object time_id)
          This method is called from the timer thread of the Socket adapter.
 void unsetName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          Implementation of I_OverlaySocket.unsetName().
 void unsetName(java.lang.String name)
          Implementation of I_OverlaySocket.unsetName().
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OL_Socket

public OL_Socket(hypercast.HyperCastConfig config,
                 hypercast.I_ReceiveCallback callback)
Create an overlay socket with a HyperCastConfig object and a Callback interface.

Parameters:
config - HyperCastConfig object which is used for configuration.
callback - I_ReceiveCallback interface for the application.
See Also:
OL_Socket(HyperCastConfig, I_ReceiveCallback, NotificationHandler, I_InterceptionCallback)

OL_Socket

public OL_Socket(hypercast.HyperCastConfig config,
                 hypercast.I_ReceiveCallback callback,
                 hypercast.NotificationHandler notificationHandler)
Create an overlay socket with a HyperCastConfig object, a callback object and a notification handler.

Parameters:
config - HyperCastConfig object which is used for configuration.
callback - I_ReceiveCallback interface for the application.
notificationHandler - a notification handler.
See Also:
OL_Socket(HyperCastConfig, I_ReceiveCallback, NotificationHandler, I_InterceptionCallback)

OL_Socket

public OL_Socket(hypercast.HyperCastConfig config,
                 hypercast.I_ReceiveCallback callback,
                 hypercast.NotificationHandler notificationHandler_parameter,
                 hypercast.I_InterceptionCallback interceptionCallback)
Create an overlay socket with a HyperCastConfig object, a callback object and a notification handler.

Parameters:
config - HyperCastConfig object which is used for configuration.
callback - I_ReceiveCallback interface for the application.
notificationHandler_parameter - a notification handler.
interceptionCallback - a interception object.
Method Detail

getStreamManager

public hypercast.StreamManager getStreamManager()
Specified by:
getStreamManager in interface I_OverlaySocket

ReceiveCallback

public void ReceiveCallback(hypercast.I_OverlayMessage message)
TODO: document me!

Specified by:
ReceiveCallback in interface I_ReceiveCallback

joinOverlay

public void joinOverlay()

Implements the operation of joining an overlay network. The call is asynchronous in the sense that upon return to the caller, the socket has *not necessarily* completed the join operation of the particular overlay protocol (or protocols in the multi-node case NB multi-node is not implemented as of Fall 2004). If an application is interested in knowing when the join operation is complete it must use the notification mechanism to receive such an event.

This call is responsible for starting all threads needed by the socket that were not started at socket construction time. These threads should be stopped in reverse order by leaveOverlay().

Specified by:
joinOverlay in interface I_OverlaySocket
See Also:
leaveOverlay()

leaveOverlay

public void leaveOverlay()
Leaves a multicast group, stopping all threads started by joinOverlay() in reverse order.

Specified by:
leaveOverlay in interface I_OverlaySocket
See Also:
joinOverlay()

closeSocket

public void closeSocket()
This method permanently closes the socket. It does a clean close, i.e. it will first leave the overlay if the socket has not already done so, thus executing any delayed leaveOverlay that certain protocols require. Then it stops the internal thread of the notification handler, and finally closes the adapters. This call blocks until the socket finishes shutting down. Any delayed stop in the protocols is completed before the socket closes and this call unblocks.

Specified by:
closeSocket in interface I_OverlaySocket

setName

public void setName(java.lang.String name)

Implementation of I_OverlaySocket.setName(). Delegates call to an instance of Naming.

Specified by:
setName in interface I_OverlaySocket
Parameters:
name - The string that will be set as the name of this overlay socket.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.setName(String)

setName

public void setName(java.lang.String name,
                    hypercast.I_LogicalAddress logicalAddress)
Description copied from interface: I_OverlaySocket

Assigns the specified name to the specified logical address. The logical address can be any address in the current logical address space. This operation allows bindings to be created for the logical addresses of sockets other than the local socket.

Specified by:
setName in interface I_OverlaySocket
Parameters:
name - The string that will be used as the name of a new binding.
logicalAddress - The logical address that will be used as the logical address of a new binding.

setName

public void setName(java.security.cert.Certificate certificate,
                    java.security.PrivateKey privateKey)

Implementation of I_OverlaySocket.setName(). Delegates call to an instance of Naming.

Specified by:
setName in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.setName(Certificate, PrivateKey)

setName

public void setName(java.security.cert.Certificate certificate,
                    java.security.PrivateKey privateKey,
                    java.lang.String name,
                    hypercast.I_LogicalAddress logicalAddress)
Description copied from interface: I_OverlaySocket

Assigns the specified name to the specified logical address using the specified private key (that matches the public key in the specified certificate) to create a digital signature for the new binding. The subject common name of the specified certificate is used as the signer name of the binding. The logical address can be any address in the current logical address space. This operation allows bindings to be created for the logical addresses of sockets other than the local socket.

Specified by:
setName in interface I_OverlaySocket
Parameters:
name - The string that will be used as the name of a new binding.
logicalAddress - The logical address that will be used as the logical address of a new binding.
certificate - Certificate that contains the name that will be the signer of the new binding.
privateKey - Key used to create a digital signature for a new binding

unsetName

public void unsetName(java.lang.String name)

Implementation of I_OverlaySocket.unsetName(). Delegates call to an instance of Naming.

Specified by:
unsetName in interface I_OverlaySocket
Parameters:
name - The string that will be unset as the name of this overlay socket.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.unsetName(String)

unsetName

public void unsetName(java.security.cert.Certificate certificate,
                      java.security.PrivateKey privateKey)

Implementation of I_OverlaySocket.unsetName(). Delegates call to an instance of Naming.

Specified by:
unsetName in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.unsetName(Certificate, PrivateKey)

namingLogicalAddressChange

public void namingLogicalAddressChange()

Implementation of I_OverlaySocket.namingLogicalAddressChange(). Delegates call to an instance of Naming.

Specified by:
namingLogicalAddressChange in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.namingLogicalAddressChange()

getNames

public java.lang.String[] getNames()

Implementation of I_OverlaySocket.getName(). Delegates call to an instance of Naming.

Specified by:
getNames in interface I_OverlaySocket
Returns:
The name of this overlay socket, never null since the lookup is local.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getNames()

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress logicalAddress)

Implementation of I_OverlaySocket.getName(I_LogicalAddress). Delegates call to an instance of Naming.

Specified by:
getNames in interface I_OverlaySocket
Parameters:
logicalAddress - The logical address of the node for which a name is requested.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getNames(I_LogicalAddress)

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer,
                                   boolean requireTrusted,
                                   long timeout,
                                   boolean requireSerialNumberMatch,
                                   boolean requireAuthoritative,
                                   int maxAge,
                                   int maxResponses,
                                   short maxHopCount,
                                   short minHopCount)

Implementation of I_OverlaySocket.getName(I_LogicalAddress,boolean,long,boolean,boolean,int,int,short). Delegates call to an instance of Naming.

Specified by:
getNames in interface I_OverlaySocket
Parameters:
peer - The logical address of the node for which a name is requested.
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
maxHopCount - The minimum number of hops that a query must make before it is not propagated further.
minHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
A array of the names of the overlay sockets having the given logical address
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress address)

Implementation of I_OverlaySocket.getNameNonBlocking(I_LogicalAddress). Delegates call to an instance of Naming.

Specified by:
getNamesNonBlocking in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getNamesNonBlocking(I_LogicalAddress)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress peer,
                               boolean requireTrusted,
                               long timeout,
                               boolean requireSerialNumberMatch,
                               boolean requireAuthoritative,
                               int maxAge,
                               int maxResponses,
                               short minHopCount,
                               short maxHopCount)

Implementation of I_OverlaySocket.getNameNonBlocking(I_LogicalAddress). Delegates call to an instance of Naming.

Specified by:
getNamesNonBlocking in interface I_OverlaySocket
Parameters:
peer - The logical address of the node for which a name is requested.
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
maxHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
serial number of query
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getNamesNonBlocking(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)

Implementation of I_OverlaySocket.getLogicalAddress(String). Delegates call to an instance of Naming.

Specified by:
getLogicalAddressByName in interface I_OverlaySocket
Parameters:
name - The name of a socket for which the logical address is requested.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getLogicalAddressByName(String)

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name,
                                                            boolean requireTrusted,
                                                            long timeout,
                                                            boolean requireSerialNumberMatch,
                                                            boolean requireAuthoritative,
                                                            int maxAge,
                                                            int maxResponses,
                                                            short minHopCount,
                                                            short maxHopCount)

Implementation of I_OverlaySocket.getLogicalAddress(String). Delegates call to an instance of Naming.

Specified by:
getLogicalAddressByName in interface I_OverlaySocket
Parameters:
name - The name for which a logical address lookup is being performed
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
maxHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
A array of the logical addresses of the sockets with the given name.
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getLogicalAddressByName(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name)

Implementation of I_OverlaySocket.getLogicalAddressNonBlocking(String). Delegates call to an instance of Naming.

Specified by:
getLogicalAddressByNameNonBlocking in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getLogicalAddressByNameNonBlocking(String)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name,
                                              boolean requireTrusted,
                                              long timeout,
                                              boolean requireSerialNumberMatch,
                                              boolean requireAuthoritative,
                                              int maxAge,
                                              int maxResponses,
                                              short minHopCount,
                                              short maxHopCount)

Implementation of I_OverlaySocket.getLogicalAddressNonBlocking(String). Delegates call to an instance of Naming.

Specified by:
getLogicalAddressByNameNonBlocking in interface I_OverlaySocket
Parameters:
name - The name for which a logical address lookup is being performed
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
maxHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
serial number of query
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

installTrustedNamingCertificate

public void installTrustedNamingCertificate(java.security.cert.Certificate certificate)

Implementation of I_OverlaySocket.installTrustedNamingCertificate(). Delegates call to an instance of Naming.

Specified by:
installTrustedNamingCertificate in interface I_OverlaySocket
Throws:
java.lang.UnsupportedOperationException - if naming is not configured
See Also:
Naming, I_OverlaySocket.installTrustedNamingCertificate(Certificate)

createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                int length)
Deprecated. The length parameter is redundant.


createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                int length,
                                                int servicenumber)
Deprecated. The length parameter is redundant.


createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                int length,
                                                byte[] streamid)
Deprecated. The length parameter is redundant.


createMessage

public hypercast.I_OverlayMessage createMessage()
Same as calling createMessage(byte []) with parameter of null.

See Also:
createMessage(byte [])

createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload)
Creates an overlay message with an application payload extension.

Specified by:
createMessage in interface I_OverlaySocket
Parameters:
payload - The payload of the message.

createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                short serviceNumber)
Create an OL_Message containing an extension that contains an appliction payload extension and a message store extension.

Specified by:
createMessage in interface I_OverlaySocket
Parameters:
payload - The data of the application program
serviceNumber - The service (FSM) that will handle the application data message
Throws:
HyperCastWarningRuntimeException - if message store is not active or service type is not supported

createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                byte[] streamid)
Creates a message with specified stream id.

Parameters:
payload - the payload of the new message, it will be stored in a payload extension
streamid - the stream id that identifies the service that the new message will be associated with (for (de)multiplexing), this value must be 4 bytes in length
Returns:
a new overlay message with an FSM extension and a payload extension. This message will be processed by a message store.
Throws:
HyperCastWarningRuntimeException - if there is no message store configured, this is not a configuration exception because the programmer choose to create this message despite the configuration which may be correct or incorrect.

createLogicalAddress

public hypercast.I_LogicalAddress createLogicalAddress(byte[] encodedLogicalAddress,
                                                       int offset)
Creates an I_LogicalAddress from a bytes array

Specified by:
createLogicalAddress in interface I_OverlaySocket

createLogicalAddress

public hypercast.I_LogicalAddress createLogicalAddress(java.lang.String logicalAddressString)
Creates a logical address object from a String.

Specified by:
createLogicalAddress in interface I_OverlaySocket

setLogicalAddress

public void setLogicalAddress(hypercast.I_LogicalAddress logicalAddress)
Sets the logical address to specified one.

Specified by:
setLogicalAddress in interface I_OverlaySocket

getLogicalAddress

public hypercast.I_LogicalAddress getLogicalAddress()
Returns the node's logical address

Specified by:
getLogicalAddress in interface I_OverlaySocket

appmsgArrived

public void appmsgArrived(hypercast.I_OverlayMessage message,
                          hypercast.I_ReceiveCallback callback)
Passes the message to the application via the callback. This serves as the central point to pass messages to the application, subclasses can implement this method to do subclass specific operations, e.g. decrypt/encrypted payload before delivering to the application.


getUniqueIdentifier

public byte[] getUniqueIdentifier()
Returns the unique identifier for this node. It is actually the node physical address byte array.

Specified by:
getUniqueIdentifier in interface I_OverlaySocket

generateMsgIdentifier

public short generateMsgIdentifier()
Returns a message identifier.


generateStreamIdentifier

public short generateStreamIdentifier()
Returns a stream identifier.


getParent

public hypercast.I_LogicalAddress getParent(hypercast.I_LogicalAddress root)
Returns this node's parent with respect to a tree starting at "root".

Specified by:
getParent in interface I_OverlaySocket

getChildren

public hypercast.I_LogicalAddress[] getChildren(hypercast.I_LogicalAddress root)
Returns an array consisting of the logical addresses of the children of this node.

Specified by:
getChildren in interface I_OverlaySocket

getNeighbors

public hypercast.I_LogicalAddress[] getNeighbors()
Returns an array consisting of the logical addresses of this node's neighbors.

Specified by:
getNeighbors in interface I_OverlaySocket

messageArrivedFromAdapter

public void messageArrivedFromAdapter(hypercast.I_Message msg)

This method implements the heart of the "Forwarding Engine." The bulk of the remaining portions of the forwarding engine can be found in the methods with the prefix "forward"

Validates the received message, delivers it to either an application or a buffering store (e.g. message store), and decides whether or not to forward it to other nodes depending on the delivery mechanism of the message and the configuration of any buffering stores. This method is called from the socket adapter thread.

This method is executed for its side effects only; there is no return value. Before calling one of the "forward" methods, this method can return, effectively dropping the message

.

Specified by:
messageArrivedFromAdapter in interface I_AdapterCallback
Parameters:
msg - The message that has arrived from the adapter.
Throws:
HyperCastWarningRuntimeException
HyperCastFatalRuntimeException

sendToAll

public void sendToAll(hypercast.I_OverlayMessage message)
Sends a multicast overlay message to all nodes in the multicast group from this socket; the sender receives a copy as well. The message may traverse multiple hops.

Specified by:
sendToAll in interface I_OverlaySocket
Parameters:
message - The overlay application message that is sent.
Throws:
HyperCastFatalRuntimeException - when the message is not an OL_Message

sendToChildren

public void sendToChildren(hypercast.I_OverlayMessage message,
                           hypercast.I_LogicalAddress root)
Sends message to all the children nodes from this socket. (Send message to children using Unicast. It is single hop)

Specified by:
sendToChildren in interface I_OverlaySocket
Parameters:
message - the overlay application message to be sent out
root - the logical address of the data source root
Throws:
HyperCastFatalRuntimeException

sendToAllNeighbors

public void sendToAllNeighbors(hypercast.I_OverlayMessage message)
Sends message to all the neighbors. Single hop, Multicast

Specified by:
sendToAllNeighbors in interface I_OverlaySocket
Parameters:
message - the overlay application message to be sent out
Throws:
HyperCastFatalRuntimeException

sendToParent

public void sendToParent(hypercast.I_OverlayMessage message,
                         hypercast.I_LogicalAddress root)
Sends a message to parent. Single hop

Specified by:
sendToParent in interface I_OverlaySocket
Parameters:
message - the overlay application message to be sent out
root - logical address of the data source root
Throws:
HyperCastFatalRuntimeException

sendToNode

public void sendToNode(hypercast.I_OverlayMessage message,
                       hypercast.I_LogicalAddress destinationLogicalAddress)
Sends a message to a specified node. Multi hops.

Specified by:
sendToNode in interface I_OverlaySocket
Parameters:
message - the overlay application message to be sent out
destinationLogicalAddress - the logical address of destination node
Throws:
HyperCastFatalRuntimeException

sendFlood

public void sendFlood(hypercast.I_OverlayMessage message)
Floods a message to all nodes.

Specified by:
sendFlood in interface I_OverlaySocket
Parameters:
message - the overlay application message to be sent out
Throws:
HyperCastFatalRuntimeException

sendIncast

public void sendIncast(hypercast.I_OverlayMessage message,
                       byte[] messageid,
                       hypercast.I_LogicalAddress root)
Send Incast message to root node.

Parameters:
message - the overlay application message to be sent out
Throws:
HyperCastFatalRuntimeException

receive

public hypercast.I_OverlayMessage receive()
Receives an overlay application message from this socket. This call will block until there a message returns.

Specified by:
receive in interface I_OverlaySocket
Returns:
overlay application message This method should be called *ONLY* when the user has NOT specified a callback to the constructor

setSoTimeout

public void setSoTimeout(int timeout)
Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a non-zero timeout, a call to receive() for this OL_Socket will block for only this amount of time. If the timeout expires, a java.io.InterruptedIOException is raised, though the OL_Socket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout.

Specified by:
setSoTimeout in interface I_OverlaySocket
Parameters:
timeout - the specified timeout in milliseconds.

getSoTimeout

public int getSoTimeout()
Retrive setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e., timeout of infinity).

Specified by:
getSoTimeout in interface I_OverlaySocket
Returns:
the setting for SO_TIMEOUT

setHopLimit

public void setHopLimit(short hopLimit)
Set the default hop limit for multicast packets sent out on this socket. The hop limit sets the IP hop limit for DatagramPackets sent to a MulticastGroup, which specifies how many "hops" that the packet will be forwarded on the network before it expires. The hop limit is an unsigned 16-bit quantity

Specified by:
setHopLimit in interface I_OverlaySocket
See Also:
for an explanation of the interpretation of the field value.

getHopLimit

public short getHopLimit()
Get the default hop limit for multicast packets sent out on the OL_Socket.

Specified by:
getHopLimit in interface I_OverlaySocket
Returns:
the default hop limit value

timerExpired

public void timerExpired(java.lang.Object time_id)
This method is called from the timer thread of the Socket adapter. This timer is used by the message store.

Specified by:
timerExpired in interface I_AdapterCallback

restoreMessage

public hypercast.I_Message restoreMessage(byte[] recvbuff,
                                          int[] validBytesStart,
                                          int validBytesEnd)
Creates an I_Message from a byte array.

Specified by:
restoreMessage in interface I_AdapterCallback
Parameters:
recvbuff - byte array of data
validBytesStart - the offset from where to create the message
validBytesEnd - the total valid bytes length in this array
Returns:
an I_Message object or null if the array contains no complete I_Message

getStatsName

public java.lang.String getStatsName()
Description copied from interface: I_Stats
Gets the element name of this I_Stats instance. The element name is originally assigned from the attribute StstsName in the configuration file, and can be changed by this method.

Specified by:
getStatsName in interface I_Stats
See Also:
I_Stats.getStatsName()

setStatsName

public void setStatsName(java.lang.String name)
Description copied from interface: I_Stats
Assigns a name to this I_Stats instance. The assigned name becomes the tag of the element associated to this I_Stats instance on the statistics tree.

Specified by:
setStatsName in interface I_Stats
Parameters:
name - the name assigned to the I_Stats instance.
See Also:
I_Stats.setStatsName(String)

getStats

public org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath)
                               throws HyperCastStatsException
Description copied from interface: I_Stats
Gets statistics information from an object which implements this interface. Statistics are arranged in a tree structure. This method has the ability to query an arbitrary subtree.

Specified by:
getStats in interface I_Stats
Parameters:
xpath - Specifies the statistic subtree to query.
doc - The document is used as a factory to create XML objects such as Nodes and Elements as needed. TODO: describe how the XML document in the doc is used.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree.
See Also:
I_Stats.getStats(org.w3c.dom.Document, org.apache.xpath.XPath)

setStats

public org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath,
                                      org.w3c.dom.Element newValue)
                               throws HyperCastStatsException
Description copied from interface: I_Stats
Sets statistics information for an object which implements this interface. Statistics are arranged in a tree structure. This method has the ability to set an arbitrary subtree of statistics.

Specified by:
setStats in interface I_Stats
Parameters:
xpath - Specifies the statistic subtree to use when updating values.
doc - The document is used as a factory to create XML objects such as Nodes and Elements as needed. TODO: describe how the XML document in the doc is used.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree or if any part of the the subtree is read-only, or if the newValue does not conform with the expected format.
See Also:
I_Stats.setStats(org.w3c.dom.Document, org.apache.xpath.XPath, org.w3c.dom.Element)

getReadSchema

public org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc,
                                           org.apache.xpath.XPath xpath)
                                    throws HyperCastStatsException
Description copied from interface: I_Stats
Dynamically generates a subtree of the Readable Schema rooted at the path specified by the xpath. The Readable Schema is distrubuted among the componenets of hypercast. Each component knows how to generate its portion of the Readable Schema. If a component has sub-components, it calls getReadSchema recursively. Note that the Readable Schema is disjoint from the Writable Schema. The Readable Schema is not modeled as a subset of the Writable Schema.

Specified by:
getReadSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getReadSchema(org.w3c.dom.Document, org.apache.xpath.XPath)

getWriteSchema

public org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc,
                                            org.apache.xpath.XPath xpath)
                                     throws HyperCastStatsException
Description copied from interface: I_Stats
Dynamically generates a subtree of the Writable Schema rooted at the path specified by the xpath. The Writable Schema is distrubuted among the componenets of hypercast. Each component knows how to generate its portion of the Writable Schema. If a component has sub-components, it calls getWriteSchema recursively. Note that the Readable Schema is disjoint from the Writable Schema. The Readable Schema is not modeled as a subset of the Writable Schema.

Specified by:
getWriteSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getWriteSchema(org.w3c.dom.Document, org.apache.xpath.XPath)