hypercast
Class HyperCastAppl

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

public abstract class HyperCastAppl
extends java.lang.Object
implements I_OverlaySocket, I_ReceiveCallback

The HyperCast Application Object is intended to be a simplified interface to the HyperCast system. Instead of using the Berkeley Sockets paradigm, an object-oriented approach is used. User code simply extends this object to create a HyperCast application.


Field Summary
static int EXCEPTION_IGNORE
          do nothing when exception is caught
static int EXCEPTION_LOG
          catch exception and output to log
static int EXCEPTION_LOG_AND_THROW
          catch exception and output to log then re-throw exception to user
static int EXCEPTION_THROW
          re-throw exception to user
 
Fields inherited from interface hypercast.I_OverlaySocket
HOP_LIMIT_MAXIMUM
 
Constructor Summary
HyperCastAppl()
          Creates a HyperCast application object with defaults for configuration filename and exception actions.
HyperCastAppl(int warningAction, int fatalAction)
          Creates a HyperCast application object with the specified values for exception actions and default configuration filename.
HyperCastAppl(int warningAction, int fatalAction, java.lang.String configurationFilename)
          Creates a HyperCast application object with the specified values for exception actions and the specified value for the configuration filename.
HyperCastAppl(java.lang.String configurationFilename)
          Creates a HyperCast application object with the specified configuration filename and defaults for exception actions.
 
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 laddr)
          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.
 int getFatalAction()
           
 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 peer)
          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.
 org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          I_Stats#getReadSchema
 int getSoTimeout()
          Get the timeout for any thread calling receive().
 org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          I_Stats#getStats
 java.lang.String getStatsName()
          Gets the element name of this I_Stats instance.
 hypercast.StreamManager getStreamManager()
           
 byte[] getUniqueIdentifier()
          Returns a byte array containing a unique identifier of this socket.
 int getWarningAction()
           
 org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          I_Stats#getWriteSchema
 void handle_E2EACK_RECEIVED(hypercast.events.E2EACK_RECEIVED event)
           
 void handle_E2EPARTIALACK_RECEIVED(hypercast.events.E2EPARTIALACK_RECEIVED event)
           
 void handle_NAMING_EVENT(hypercast.events.NAMING_EVENT event)
           
 void handle_NEWSTREAM_ARRIVED_EVENT(hypercast.events.NEWSTREAM_ARRIVED_EVENT event)
           
 void handle_NODE_ISSTABLE(hypercast.events.NODE_ISSTABLE event)
           
 void handle_NODE_LEAVEOVERLAY(hypercast.events.NODE_LEAVEOVERLAY event)
           
 void handle_NODE_LOGICALADDRESSCHANGED(hypercast.events.NODE_LOGICALADDRESSCHANGED event)
           
 void handle_NODE_NEIGHBORHOODCHANGED(hypercast.events.NODE_NEIGHBORHOODCHANGED event)
           
 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 ReceiveCallback(hypercast.I_OverlayMessage message)
          Application overrides this method to receive messages.
 void sendFlood(hypercast.I_OverlayMessage message)
          Sends the message to all nodes using a "flood" routing mechanism.
 void sendToAll(hypercast.I_OverlayMessage message)
          Sends the message to all members of the overlay topology.
 void sendToAllNeighbors(hypercast.I_OverlayMessage message)
          Sends the message one hop to all neighbors of this socket in the overlay.
 void sendToChildren(hypercast.I_OverlayMessage message, 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 message, hypercast.I_LogicalAddress destination)
          Sends the message unicast over the overlay to the destination.
 void sendToParent(hypercast.I_OverlayMessage message, hypercast.I_LogicalAddress root)
          Sends this message one hop to the parent of this socket in the spanning tree rooted at root.
 void setFatalAction(int action)
          Sets the action taken when a HyperCastFatalRuntimeException occurs.
 void setHopLimit(short hopLimit)
          Sets the default hop limit for all future messages created by createMessage.
 void setLogicalAddress(hypercast.I_LogicalAddress address)
          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().
 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 setWarningAction(int action)
          Sets the action taken when a HyperCastWarningRuntimeException is occurs.
 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.
 hypercast.events.E2EACK_RECEIVED waitUntil_E2EACK_RECEIVED()
           
 hypercast.events.E2EACK_RECEIVED waitUntil_E2EACK_RECEIVED(long timeout)
           
 hypercast.events.E2EPARTIALACK_RECEIVED waitUntil_E2EPARTIALACK_RECEIVED()
           
 hypercast.events.E2EPARTIALACK_RECEIVED waitUntil_E2EPARTIALACK_RECEIVED(long timeout)
           
 hypercast.events.NAMING_EVENT waitUntil_NAMING_EVENT()
           
 hypercast.events.NAMING_EVENT waitUntil_NAMING_EVENT(long timeout)
           
 hypercast.events.NEWSTREAM_ARRIVED_EVENT waitUntil_NEWSTREAM_ARRIVED_EVENT()
           
 hypercast.events.NEWSTREAM_ARRIVED_EVENT waitUntil_NEWSTREAM_ARRIVED_EVENT(long timeout)
           
 hypercast.events.NODE_ISSTABLE waitUntil_NODE_ISSTABLE()
           
 hypercast.events.NODE_ISSTABLE waitUntil_NODE_ISSTABLE(long timeout)
           
 hypercast.events.NODE_LEAVEOVERLAY waitUntil_NODE_LEAVEOVERLAY()
           
 hypercast.events.NODE_LEAVEOVERLAY waitUntil_NODE_LEAVEOVERLAY(long timeout)
           
 hypercast.events.NODE_LOGICALADDRESSCHANGED waitUntil_NODE_LOGICALADDRESSCHANGED()
           
 hypercast.events.NODE_LOGICALADDRESSCHANGED waitUntil_NODE_LOGICALADDRESSCHANGED(long timeout)
           
 hypercast.events.NODE_NEIGHBORHOODCHANGED waitUntil_NODE_NEIGHBORHOODCHANGED()
           
 hypercast.events.NODE_NEIGHBORHOODCHANGED waitUntil_NODE_NEIGHBORHOODCHANGED(long timeout)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EXCEPTION_LOG

public static final int EXCEPTION_LOG
catch exception and output to log

See Also:
Constant Field Values

EXCEPTION_THROW

public static final int EXCEPTION_THROW
re-throw exception to user

See Also:
Constant Field Values

EXCEPTION_LOG_AND_THROW

public static final int EXCEPTION_LOG_AND_THROW
catch exception and output to log then re-throw exception to user

See Also:
Constant Field Values

EXCEPTION_IGNORE

public static final int EXCEPTION_IGNORE
do nothing when exception is caught

See Also:
Constant Field Values
Constructor Detail

HyperCastAppl

public HyperCastAppl()
Creates a HyperCast application object with defaults for configuration filename and exception actions. Relies on unified constructor.


HyperCastAppl

public HyperCastAppl(java.lang.String configurationFilename)
Creates a HyperCast application object with the specified configuration filename and defaults for exception actions. Calls unified constructor.


HyperCastAppl

public HyperCastAppl(int warningAction,
                     int fatalAction)
Creates a HyperCast application object with the specified values for exception actions and default configuration filename. Calls unified constructor.


HyperCastAppl

public HyperCastAppl(int warningAction,
                     int fatalAction,
                     java.lang.String configurationFilename)
Creates a HyperCast application object with the specified values for exception actions and the specified value for the configuration filename.

Method Detail

waitUntil_NODE_ISSTABLE

public hypercast.events.NODE_ISSTABLE waitUntil_NODE_ISSTABLE()

waitUntil_E2EACK_RECEIVED

public hypercast.events.E2EACK_RECEIVED waitUntil_E2EACK_RECEIVED()

waitUntil_E2EPARTIALACK_RECEIVED

public hypercast.events.E2EPARTIALACK_RECEIVED waitUntil_E2EPARTIALACK_RECEIVED()

waitUntil_NEWSTREAM_ARRIVED_EVENT

public hypercast.events.NEWSTREAM_ARRIVED_EVENT waitUntil_NEWSTREAM_ARRIVED_EVENT()

waitUntil_NODE_LEAVEOVERLAY

public hypercast.events.NODE_LEAVEOVERLAY waitUntil_NODE_LEAVEOVERLAY()

waitUntil_NODE_LOGICALADDRESSCHANGED

public hypercast.events.NODE_LOGICALADDRESSCHANGED waitUntil_NODE_LOGICALADDRESSCHANGED()

waitUntil_NODE_NEIGHBORHOODCHANGED

public hypercast.events.NODE_NEIGHBORHOODCHANGED waitUntil_NODE_NEIGHBORHOODCHANGED()

waitUntil_NAMING_EVENT

public hypercast.events.NAMING_EVENT waitUntil_NAMING_EVENT()

waitUntil_NODE_ISSTABLE

public hypercast.events.NODE_ISSTABLE waitUntil_NODE_ISSTABLE(long timeout)

waitUntil_E2EACK_RECEIVED

public hypercast.events.E2EACK_RECEIVED waitUntil_E2EACK_RECEIVED(long timeout)

waitUntil_E2EPARTIALACK_RECEIVED

public hypercast.events.E2EPARTIALACK_RECEIVED waitUntil_E2EPARTIALACK_RECEIVED(long timeout)

waitUntil_NEWSTREAM_ARRIVED_EVENT

public hypercast.events.NEWSTREAM_ARRIVED_EVENT waitUntil_NEWSTREAM_ARRIVED_EVENT(long timeout)

waitUntil_NODE_LEAVEOVERLAY

public hypercast.events.NODE_LEAVEOVERLAY waitUntil_NODE_LEAVEOVERLAY(long timeout)

waitUntil_NODE_LOGICALADDRESSCHANGED

public hypercast.events.NODE_LOGICALADDRESSCHANGED waitUntil_NODE_LOGICALADDRESSCHANGED(long timeout)

waitUntil_NODE_NEIGHBORHOODCHANGED

public hypercast.events.NODE_NEIGHBORHOODCHANGED waitUntil_NODE_NEIGHBORHOODCHANGED(long timeout)

waitUntil_NAMING_EVENT

public hypercast.events.NAMING_EVENT waitUntil_NAMING_EVENT(long timeout)

handle_NODE_NEIGHBORHOODCHANGED

public void handle_NODE_NEIGHBORHOODCHANGED(hypercast.events.NODE_NEIGHBORHOODCHANGED event)

handle_NODE_LOGICALADDRESSCHANGED

public void handle_NODE_LOGICALADDRESSCHANGED(hypercast.events.NODE_LOGICALADDRESSCHANGED event)

handle_NODE_LEAVEOVERLAY

public void handle_NODE_LEAVEOVERLAY(hypercast.events.NODE_LEAVEOVERLAY event)

handle_NEWSTREAM_ARRIVED_EVENT

public void handle_NEWSTREAM_ARRIVED_EVENT(hypercast.events.NEWSTREAM_ARRIVED_EVENT event)

handle_E2EPARTIALACK_RECEIVED

public void handle_E2EPARTIALACK_RECEIVED(hypercast.events.E2EPARTIALACK_RECEIVED event)

handle_E2EACK_RECEIVED

public void handle_E2EACK_RECEIVED(hypercast.events.E2EACK_RECEIVED event)

handle_NODE_ISSTABLE

public void handle_NODE_ISSTABLE(hypercast.events.NODE_ISSTABLE event)

handle_NAMING_EVENT

public void handle_NAMING_EVENT(hypercast.events.NAMING_EVENT event)

ReceiveCallback

public void ReceiveCallback(hypercast.I_OverlayMessage message)
Application overrides this method to receive messages.

Specified by:
ReceiveCallback in interface I_ReceiveCallback

joinOverlay

public final void joinOverlay()
Description copied from interface: I_OverlaySocket
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.

Specified by:
joinOverlay in interface I_OverlaySocket

leaveOverlay

public final void leaveOverlay()
Description copied from interface: I_OverlaySocket
Leave the overlay multicast group.

Specified by:
leaveOverlay in interface I_OverlaySocket

closeSocket

public final void closeSocket()
Description copied from interface: I_OverlaySocket
Permanently close the socket. Once the socket has been closed, it cannot join an overlay.

Specified by:
closeSocket in interface I_OverlaySocket

namingLogicalAddressChange

public final void namingLogicalAddressChange()
Description copied from interface: I_OverlaySocket
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.

Specified by:
namingLogicalAddressChange in interface I_OverlaySocket

createMessage

public final hypercast.I_OverlayMessage createMessage(byte[] payload)
Description copied from interface: I_OverlaySocket
Create a message for sending on the overlay socket.

Specified by:
createMessage in interface I_OverlaySocket
See Also:
OL_Socket.createMessage(byte[] payload)

createMessage

public final hypercast.I_OverlayMessage createMessage(byte[] payload,
                                                      short servicenumber)
Description copied from interface: I_OverlaySocket
Create a message with specified service number.

Specified by:
createMessage in interface I_OverlaySocket
See Also:
OL_Socket.createMessage(byte[] payload, short servicenumber)

sendToNode

public final void sendToNode(hypercast.I_OverlayMessage message,
                             hypercast.I_LogicalAddress destination)
Description copied from interface: I_OverlaySocket
Sends the message unicast over the overlay to the destination.

Specified by:
sendToNode in interface I_OverlaySocket
See Also:
OL_Socket.sendToNode(I_OverlayMessage message, I_LogicalAddress destination)

sendToParent

public final void sendToParent(hypercast.I_OverlayMessage message,
                               hypercast.I_LogicalAddress root)
Description copied from interface: I_OverlaySocket
Sends this message one hop to the parent of this socket in the spanning tree rooted at root.

Specified by:
sendToParent in interface I_OverlaySocket
See Also:
OL_Socket.sendToParent(I_OverlayMessage message, I_LogicalAddress root)

sendToChildren

public final void sendToChildren(hypercast.I_OverlayMessage message,
                                 hypercast.I_LogicalAddress root)
Description copied from interface: I_OverlaySocket
Sends the message one hop to all the children of this socket in the spanning tree rooted at root. Also see getChildren.

Specified by:
sendToChildren in interface I_OverlaySocket
See Also:
OL_Socket.sendToChildren(I_OverlayMessage message, I_LogicalAddress root)

sendToAllNeighbors

public final void sendToAllNeighbors(hypercast.I_OverlayMessage message)
Description copied from interface: I_OverlaySocket
Sends the message one hop to all neighbors of this socket in the overlay.

Specified by:
sendToAllNeighbors in interface I_OverlaySocket
See Also:
OL_Socket.sendToAllNeighbors(I_OverlayMessage message)

sendToAll

public final void sendToAll(hypercast.I_OverlayMessage message)
Description copied from interface: I_OverlaySocket
Sends the message to all members of the overlay topology. (Including self!)

Specified by:
sendToAll in interface I_OverlaySocket
See Also:
OL_Socket.sendToAll(I_OverlayMessage message)

sendFlood

public final void sendFlood(hypercast.I_OverlayMessage message)
Description copied from interface: I_OverlaySocket
Sends the message to all nodes using a "flood" routing mechanism. Some nodes may receive the message multiple times.

Specified by:
sendFlood in interface I_OverlaySocket
See Also:
OL_Socket.sendFlood(I_OverlayMessage message)

createLogicalAddress

public final hypercast.I_LogicalAddress createLogicalAddress(byte[] laddr,
                                                             int offset)
Description copied from interface: I_OverlaySocket
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().

Specified by:
createLogicalAddress in interface I_OverlaySocket
See Also:
OL_Socket.createLogicalAddress(byte[] laddr, int offset)

createLogicalAddress

public final hypercast.I_LogicalAddress createLogicalAddress(java.lang.String laddr)
Description copied from interface: I_OverlaySocket
Creates a logical address object from a String.

Specified by:
createLogicalAddress in interface I_OverlaySocket
See Also:
OL_Socket.createLogicalAddress(String laddr)

getLogicalAddress

public final hypercast.I_LogicalAddress getLogicalAddress()
Description copied from interface: I_OverlaySocket
Returns the address of this socket on the overlay.

Specified by:
getLogicalAddress in interface I_OverlaySocket
See Also:
OL_Socket.getLogicalAddress()

setLogicalAddress

public final void setLogicalAddress(hypercast.I_LogicalAddress address)
Description copied from interface: I_OverlaySocket
Sets the logical address to specified one.

Specified by:
setLogicalAddress in interface I_OverlaySocket
See Also:
OL_Socket.setLogicalAddress(I_LogicalAddress address)

getUniqueIdentifier

public final byte[] getUniqueIdentifier()
Description copied from interface: I_OverlaySocket
Returns a byte array containing a unique identifier of this socket.

Specified by:
getUniqueIdentifier in interface I_OverlaySocket
See Also:
OL_Socket.getUniqueIdentifier()

setName

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

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.

Specified by:
setName in interface I_OverlaySocket
Parameters:
name - The string that will be set as the name of this overlay socket.
See Also:
OL_Socket.setName(String)

setName

public void setName(java.security.cert.Certificate certificate,
                    java.security.PrivateKey privateKey)
Description copied from interface: I_OverlaySocket

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.

Specified by:
setName in interface I_OverlaySocket
See Also:
OL_Socket.setName(Certificate,PrivateKey)

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.
See Also:
OL_Socket.setName(String,I_LogicalAddress)

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
See Also:
OL_Socket.setName(Certificate,PrivateKey,String,I_LogicalAddress)

unsetName

public void unsetName(java.lang.String name)
Description copied from interface: I_OverlaySocket

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.

Specified by:
unsetName in interface I_OverlaySocket
Parameters:
name - The string that will be unset as the name of this overlay socket.
See Also:
OL_Socket.unsetName(String)

unsetName

public void unsetName(java.security.cert.Certificate certificate,
                      java.security.PrivateKey privateKey)
Description copied from interface: I_OverlaySocket

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

Specified by:
unsetName in interface I_OverlaySocket
See Also:
OL_Socket.unsetName(Certificate, PrivateKey)

getNames

public java.lang.String[] getNames()
Description copied from interface: I_OverlaySocket

Queries the name of the local overlay socket.

Specified by:
getNames in interface I_OverlaySocket
Returns:
The name of this overlay socket, never null since the lookup is local.
See Also:
OL_Socket.getNames()

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
Specified by:
getNames in interface I_OverlaySocket
Parameters:
peer - The logical address of the node for which a name is requested.
See Also:
OL_Socket.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 minHopCount,
                                   short maxHopCount)
Description copied from interface: I_OverlaySocket
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.

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.
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
See Also:
OL_Socket.getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress peer)
Description copied from interface: I_OverlaySocket

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

Specified by:
getNamesNonBlocking in interface I_OverlaySocket
See Also:
OL_Socket.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)
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
See Also:
OL_Socket.getNamesNonBlocking(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
Specified by:
getLogicalAddressByName in interface I_OverlaySocket
Parameters:
name - The name of a socket for which the logical address is requested.
See Also:
OL_Socket.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)
Description copied from interface: I_OverlaySocket

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.

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.
See Also:
OL_Socket.getLogicalAddressByName(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name)
Description copied from interface: I_OverlaySocket

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

Specified by:
getLogicalAddressByNameNonBlocking in interface I_OverlaySocket
See Also:
OL_Socket.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)
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
See Also:
OL_Socket.getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

installTrustedNamingCertificate

public void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
Description copied from interface: I_OverlaySocket
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.

Specified by:
installTrustedNamingCertificate in interface I_OverlaySocket
See Also:
OL_Socket.installTrustedNamingCertificate(Certificate)

getParent

public final hypercast.I_LogicalAddress getParent(hypercast.I_LogicalAddress root)
Description copied from interface: I_OverlaySocket
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.

Specified by:
getParent in interface I_OverlaySocket
See Also:
OL_Socket.getParent(I_LogicalAddress root)

getChildren

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

Specified by:
getChildren in interface I_OverlaySocket
See Also:
OL_Socket.getChildren(I_LogicalAddress root)

getNeighbors

public final hypercast.I_LogicalAddress[] getNeighbors()
Description copied from interface: I_OverlaySocket
Returns the socket's neighbors' physical/logical address pairs.

Specified by:
getNeighbors in interface I_OverlaySocket
See Also:
OL_Socket.getNeighbors()

setHopLimit

public final void setHopLimit(short hopLimit)
Description copied from interface: I_OverlaySocket
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.

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

getHopLimit

public final short getHopLimit()
Description copied from interface: I_OverlaySocket
Gets the default hop limit for all future messages created by createMessage.

Specified by:
getHopLimit in interface I_OverlaySocket
See Also:
OL_Socket.getHopLimit()

setSoTimeout

public final void setSoTimeout(int timeout)
Description copied from interface: I_OverlaySocket
Set the timeout for any thread calling receive(). See java.net.DatagramSocket.setSoTimeout().

Specified by:
setSoTimeout in interface I_OverlaySocket
See Also:
OL_Socket.setSoTimeout(int timeout)

getSoTimeout

public final int getSoTimeout()
Description copied from interface: I_OverlaySocket
Get the timeout for any thread calling receive(). See java.net.DatagramSocket.getSoTimeout().

Specified by:
getSoTimeout in interface I_OverlaySocket
See Also:
OL_Socket.getSoTimeout()

getStreamManager

public final hypercast.StreamManager getStreamManager()
Specified by:
getStreamManager in interface I_OverlaySocket
See Also:
OL_Socket.getStreamManager()

setWarningAction

public final void setWarningAction(int action)
Sets the action taken when a HyperCastWarningRuntimeException is occurs. The user may choose any exception action as defined by the constants in this class.

See Also:
EXCEPTION_LOG, EXCEPTION_LOG_AND_THROW, EXCEPTION_THROW, EXCEPTION_IGNORE

getWarningAction

public final int getWarningAction()
Returns:
The action that will be taken when a HyperCastWarningRuntimeException occurs
See Also:
setWarningAction(int action)

setFatalAction

public final void setFatalAction(int action)
Sets the action taken when a HyperCastFatalRuntimeException occurs. The user may choose any exception action as defined by the constants in this class.

See Also:
EXCEPTION_LOG, EXCEPTION_LOG_AND_THROW, EXCEPTION_THROW, EXCEPTION_IGNORE

getFatalAction

public final int getFatalAction()
Returns:
The action that will be taken when a HyperCastWarningRuntimeException occurs
See Also:
setFatalAction(int action)

receive

public final hypercast.I_OverlayMessage receive()
Description copied from interface: I_OverlaySocket
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.

Specified by:
receive in interface I_OverlaySocket

getStats

public org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath)
                               throws HyperCastStatsException
I_Stats#getStats

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.

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
I_Stats#getReadSchema

Specified by:
getReadSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.

getWriteSchema

public org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc,
                                            org.apache.xpath.XPath xpath)
                                     throws HyperCastStatsException
I_Stats#getWriteSchema

Specified by:
getWriteSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.

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)