hypercast
Interface I_OverlaySocket

All Superinterfaces:
I_Stats
All Known Implementing Classes:
HyperCastAppl, OL_Socket

public interface I_OverlaySocket
extends I_Stats

This is the interface for a OL_socket. It defines all visible functions in the OL_Socket that can be used by an application to send and receive data on the overlay.


Field Summary
static short HOP_LIMIT_MAXIMUM
           
 
Method Summary
 void closeSocket()
          Permanently close the socket.
 hypercast.I_LogicalAddress createLogicalAddress(byte[] laddr, int offset)
          Creates a logical address from a byte array.
 hypercast.I_LogicalAddress createLogicalAddress(java.lang.String laStr)
          Creates a logical address object from a String.
 hypercast.I_OverlayMessage createMessage(byte[] payload)
          Create a message for sending on the overlay socket.
 hypercast.I_OverlayMessage createMessage(byte[] payload, short servicenumber)
          Create a message with specified service number.
 hypercast.I_LogicalAddress[] getChildren(hypercast.I_LogicalAddress root)
          Returns the socket's children's physical/logical address pairs, with respect to the spanning tree rooted at root in the overlay.
 short getHopLimit()
          Gets the default hop limit for all future messages created by createMessage.
 hypercast.I_LogicalAddress getLogicalAddress()
          Returns the address of this socket on the overlay.
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
           
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Queries the logical address of the overlay socket having the specified name.
 int getLogicalAddressByNameNonBlocking(java.lang.String name)
          Same as getLogicalAddress(String) but returns immediately.
 int getLogicalAddressByNameNonBlocking(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
           
 java.lang.String[] getNames()
          Queries the name of the local overlay socket.
 java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
           
 java.lang.String[] getNames(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Queries the name of the overlay socket with logical address peer.
 int getNamesNonBlocking(hypercast.I_LogicalAddress address)
          Same as getNames(I_LogicalAddress) but returns immediately.
 int getNamesNonBlocking(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
           
 hypercast.I_LogicalAddress[] getNeighbors()
          Returns the socket's neighbors' physical/logical address pairs.
 hypercast.I_LogicalAddress getParent(hypercast.I_LogicalAddress root)
          Returns the addresspair of the next hop for a message routed by this socket towards the root.
 int getSoTimeout()
          Get the timeout for any thread calling receive().
 hypercast.StreamManager getStreamManager()
           
 byte[] getUniqueIdentifier()
          Returns a byte array containing a unique identifier of this socket.
 void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
          Installs a trust anchor for use in building chains of trust.
 void joinOverlay()
          Join the overlay multicast group.
 void leaveOverlay()
          Leave the overlay multicast group.
 void namingLogicalAddressChange()
          Signals to the naming service that the logical address of the node has changed.
 hypercast.I_OverlayMessage receive()
          Receive a message.
 void sendFlood(hypercast.I_OverlayMessage m)
          Sends the message to all nodes using a "flood" routing mechanism.
 void sendToAll(hypercast.I_OverlayMessage m)
          Sends the message to all members of the overlay topology.
 void sendToAllNeighbors(hypercast.I_OverlayMessage m)
          Sends the message one hop to all neighbors of this socket in the overlay.
 void sendToChildren(hypercast.I_OverlayMessage m, hypercast.I_LogicalAddress root)
          Sends the message one hop to all the children of this socket in the spanning tree rooted at root.
 void sendToNode(hypercast.I_OverlayMessage m, hypercast.I_LogicalAddress destla)
          Sends the message unicast over the overlay to the destination.
 void sendToParent(hypercast.I_OverlayMessage m, hypercast.I_LogicalAddress root)
          Sends this message one hop to the parent of this socket in the spanning tree rooted at root.
 void setHopLimit(short hopLimit)
          Sets the default hop limit for all future messages created by createMessage.
 void setLogicalAddress(hypercast.I_LogicalAddress la)
          Sets the logical address to specified one.
 void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          This method is like setName(String) but the subject common name of the given certificate is used as the name string instead of a Java String object.
 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)
          Binds the specified name to the logical address of this overlay socket.
 void setName(java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
          Assigns the specified name to the specified logical address.
 void setSoTimeout(int timeout)
          Set the timeout for any thread calling receive().
 void unsetName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          This method is like unsetName(String) but uses a certificate instead of a String, it is the inverse of setName(Certificate,PrivateKey).
 void unsetName(java.lang.String name)
          Unassigns the given name from this overlay socket.
 
Methods inherited from interface hypercast.I_Stats
getReadSchema, getStats, getStatsName, getWriteSchema, setStats, setStatsName
 

Field Detail

HOP_LIMIT_MAXIMUM

public static final short HOP_LIMIT_MAXIMUM
See Also:
Constant Field Values
Method Detail

joinOverlay

public void joinOverlay()
Join the overlay multicast group. NOTE: It may take a while for the overlay to stabilize; right after joining some sends may not reach all members of the group.


leaveOverlay

public void leaveOverlay()
Leave the overlay multicast group.


closeSocket

public void closeSocket()
Permanently close the socket. Once the socket has been closed, it cannot join an overlay.


createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload)
Create a message for sending on the overlay socket.


createMessage

public hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                short servicenumber)
Create a message with specified service number.


createLogicalAddress

public hypercast.I_LogicalAddress createLogicalAddress(byte[] laddr,
                                                       int offset)
Creates a logical address from a byte array. This enables applications to send logical addresses in messages. The number of bytes read is equal to I_OverlaySocket.getLogicalAddress().getSize().


createLogicalAddress

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


setLogicalAddress

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


getLogicalAddress

public hypercast.I_LogicalAddress getLogicalAddress()
Returns the address of this socket on the overlay.


getUniqueIdentifier

public byte[] getUniqueIdentifier()
Returns a byte array containing a unique identifier of this socket.


setName

public void setName(java.lang.String name)

Binds the specified name to the logical address of this overlay socket. This operation might cause the new binding to be "pushed" to other peers in the network, depending upon the policy configuration of the socket. The global uniqueness of the names of overlay sockets is neither enforced nor required. The set of all bindings with a particular name defines a group.

Parameters:
name - The string that will be set as the name of this overlay socket.
Throws:
HyperCastWarningRuntimeException - if the argument is null

setName

public void setName(java.lang.String name,
                    hypercast.I_LogicalAddress logicalAddress)

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.

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)

This method is like setName(String) but the subject common name of the given certificate is used as the name string instead of a Java String object. Also, a private key, cooresponding to the public key in the certificate, is given so that naming message that are sent to peers can be cryptographically signed.


setName

public 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. 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.

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)

Unassigns the given name from this overlay socket. This operation might cause an invalidation operation for the name to be "pushed" to other nodes in the network, depending upon the policy configuration of the socket.

Parameters:
name - The string that will be unset as the name of this overlay socket.
Throws:
HyperCastWarningRuntimeException - if the argument is null

unsetName

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

This method is like unsetName(String) but uses a certificate instead of a String, it is the inverse of setName(Certificate,PrivateKey).


getNames

public java.lang.String[] getNames()

Queries the name of the local overlay socket.

Returns:
The name of this overlay socket, never null since the lookup is local.

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
Parameters:
peer - The logical address of the node for which a name is requested.
See Also:
getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer,
                                   boolean requireTrusted,
                                   long timeout,
                                   boolean requireSerialNumberMatch,
                                   boolean requireAuthoritative,
                                   int maxAge,
                                   int maxResponses,
                                   short minHopCount,
                                   short maxHopCount)
Queries the name of the overlay socket with logical address peer. The name returned can be the name of the local socket, if the logical address is the logical address of the local socket. This implements a "reverse lookup" function for name resolution. If the value returned is a zero length array it does not imply that no such logical address exists on the network, only that the request could not be satisfied, i.e. this call does not guarentee that it will find a name if one exists for a given logical address.

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:
A array of the names of the overlay sockets having the given logical address
Throws:
HyperCastWarningRuntimeException - if maxResponses is Naming.NO_RESPONSE_LIMIT and timeout Naming.WAIT_INDEFINITELY

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress address)

Same as getNames(I_LogicalAddress) but returns immediately. Application must handle related NAMING_EVENT notifications containing responses to this call.

See Also:
getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress peer,
                               boolean requireTrusted,
                               long timeout,
                               boolean requireSerialNumberMatch,
                               boolean requireAuthoritative,
                               int maxAge,
                               int maxResponses,
                               short minHopCount,
                               short maxHopCount)
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
See Also:
getNamesNonBlocking(I_LogicalAddress)

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
Parameters:
name - The name of a socket for which the logical address is requested.
See Also:
[] getLogicalAddressByName(String,boolean,long,boolean,int,int,short)

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)

Queries the logical address of the overlay socket having the specified name. If no such socket can be found, a zero length array is returned. A result of a zero length array does not imply that no such socket exists, only that one could not be found, i.e. this call does not guarentee that it will find a logical address if one exists for a given name.

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:
HyperCastWarningRuntimeException - if maxResponses is Naming.NO_RESPONSE_LIMIT and timeout Naming.WAIT_INDEFINITELY

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name)

Same as getLogicalAddress(String) but returns immediately. Application must handle related NAMING_EVENT notifications containing responses to this call.

See Also:
getLogicalAddressByName(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name,
                                              boolean requireTrusted,
                                              long timeout,
                                              boolean requireSerialNumberMatch,
                                              boolean requireAuthoritative,
                                              int maxAge,
                                              int maxResponses,
                                              short minHopCount,
                                              short maxHopCount)
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
See Also:
getLogicalAddressByNameNonBlocking(String)

installTrustedNamingCertificate

public void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
Installs a trust anchor for use in building chains of trust. Trust is established for naming bindings by verifying the signature of the binding using the certificate that created the signature. That certificate becomes trusted when a chain of trust can be established from it to an installed trust anchor.


namingLogicalAddressChange

public void namingLogicalAddressChange()
Signals to the naming service that the logical address of the node has changed. If the naming service is used, the user must implement some method of checking for logical address changes, and then invoking this method when the logical address changes.


getParent

public hypercast.I_LogicalAddress getParent(hypercast.I_LogicalAddress root)
Returns the addresspair of the next hop for a message routed by this socket towards the root. The next hop would be the node's parent in the spanning tree rooted at root.

Throws:
java.lang.IllegalStateException - if socket has not joined group.

getChildren

public hypercast.I_LogicalAddress[] getChildren(hypercast.I_LogicalAddress root)
Returns the socket's children's physical/logical address pairs, with respect to the spanning tree rooted at root in the overlay.

Throws:
java.lang.IllegalStateException - if socket has not joined group.

getNeighbors

public hypercast.I_LogicalAddress[] getNeighbors()
Returns the socket's neighbors' physical/logical address pairs.

Throws:
java.lang.IllegalStateException - if socket has not joined group.

setHopLimit

public void setHopLimit(short hopLimit)
Sets the default hop limit for all future messages created by createMessage. It can be overriden on a per-message basis by I_OverlayMessage.setHopLimit.

See Also:
for an explanation of the interpretation of the field value.

getHopLimit

public short getHopLimit()
Gets the default hop limit for all future messages created by createMessage.


sendToAll

public void sendToAll(hypercast.I_OverlayMessage m)
Sends the message to all members of the overlay topology. (Including self!)


sendToChildren

public void sendToChildren(hypercast.I_OverlayMessage m,
                           hypercast.I_LogicalAddress root)
Sends the message one hop to all the children of this socket in the spanning tree rooted at root. Also see getChildren.


sendToAllNeighbors

public void sendToAllNeighbors(hypercast.I_OverlayMessage m)
Sends the message one hop to all neighbors of this socket in the overlay.


sendToParent

public void sendToParent(hypercast.I_OverlayMessage m,
                         hypercast.I_LogicalAddress root)
Sends this message one hop to the parent of this socket in the spanning tree rooted at root.


sendToNode

public void sendToNode(hypercast.I_OverlayMessage m,
                       hypercast.I_LogicalAddress destla)
Sends the message unicast over the overlay to the destination.


sendFlood

public void sendFlood(hypercast.I_OverlayMessage m)
Sends the message to all nodes using a "flood" routing mechanism. Some nodes may receive the message multiple times.


receive

public hypercast.I_OverlayMessage receive()
Receive a message. This can only be used if no object implementing I_ReceiveCallback was passed to the constructor of the socket. (e.g., config.createSocket(null)). The thread doing this call can be interrupted.

Throws:
throws - IllegalStateException if a callback has been specified.

setSoTimeout

public void setSoTimeout(int timeout)
Set the timeout for any thread calling receive(). See java.net.DatagramSocket.setSoTimeout().


getSoTimeout

public int getSoTimeout()
Get the timeout for any thread calling receive(). See java.net.DatagramSocket.getSoTimeout().


getStreamManager

public hypercast.StreamManager getStreamManager()