edu.virginia.cs.mng.hypercast
Interface I_OverlaySocket

public abstract interface I_OverlaySocket
extends I_Stats

This is the interface for a socket to send and receive data on the overlay. To construct one, see OverlaySocketConfig.createSocket. Before using the socket, the application must call joinGroup(). To send data to everyone, follow this example code:

OverlayManager om = new OverlayManager("hypercast.prop"); OverlaySocketConfig config = om.getOverlaySocketConfig(om.getDefaultProperty("Overlay")); I_OverlaySocket sock = config.createSocket(null); sock.joinGroup(); byte[] data = "Hello World!".getBytes(); I_OverlayMessage msg = sock.createMessage(data, data.length); sock.sendToAll(msg);

Method Summary
 I_LogicalAddress createLogicalAddress(byte[] laddr, int offset)
          Creates a logical address from a byte array.
 I_OverlayMessage createMessage(byte[] payload, int length)
          Create a message for sending on the overlay socket.
 I_LogicalAddress[] getChildren(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.
 I_LogicalAddress getLogicalAddress()
          Returns the address of this socket on the overlay.
 I_LogicalAddress[] getNeighbors()
          Returns the socket's neighbors' physical/logical address pairs.
 I_LogicalAddress getParent(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().
 int getTTL()
          Gets the default Time-to-Live for all future messages created by createMessage.
 byte[] getUniqueIdentifier()
          Returns a byte array containing a unique identifier of this socket.
 void joinGroup()
          Join the overlay multicast group.
 void leaveGroup()
          Leave the overlay multicast group.
 I_OverlayMessage receive()
          Receive a message.
 void sendFlood(I_OverlayMessage m)
          Sends the message to all nodes using a "flood" routing mechanism.
 void sendToAll(I_OverlayMessage m)
          Sends the message to all members of the overlay topology.
 void sendToAllNeighbors(I_OverlayMessage m)
          Sends the message one hop to all neighbors of this socket in the overlay.
 void sendToChildren(I_OverlayMessage m, I_LogicalAddress root)
          Sends the message one hop to all the children of this socket in the spanning tree rooted at root.
 void sendToNode(I_OverlayMessage m, I_LogicalAddress destla)
          Sends the message unicast over the overlay to the destination.
 void sendToParent(I_OverlayMessage m, I_LogicalAddress root)
          Sends this message one hop to the parent of this socket in the spanning tree rooted at root.
 void setSoTimeout(int timeout)
          Set the timeout for any thread calling receive().
 void setTTL(int ttl)
          Sets the default Time-to-Live for all future messages created by createMessage.
 
Methods inherited from interface edu.virginia.cs.mng.hypercast.I_Stats
getSchema, getStats, setStats
 

Method Detail

joinGroup

public void joinGroup()
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.

leaveGroup

public void leaveGroup()
Leave the overlay multicast group.

createMessage

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

createLogicalAddress

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

getLogicalAddress

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

getParent

public I_LogicalAddress getParent(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 I_LogicalAddress[] getChildren(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 I_LogicalAddress[] getNeighbors()
Returns the socket's neighbors' physical/logical address pairs.
Throws:
java.lang.IllegalStateException - if socket has not joined group.

setTTL

public void setTTL(int ttl)
Sets the default Time-to-Live for all future messages created by createMessage. It can be overriden on a per-message basis by I_OverlayMessage.setTTL

getTTL

public int getTTL()
Gets the default Time-to-Live for all future messages created by createMessage.

sendToAll

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

sendToChildren

public void sendToChildren(I_OverlayMessage m,
                           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(I_OverlayMessage m)
Sends the message one hop to all neighbors of this socket in the overlay.

sendToParent

public void sendToParent(I_OverlayMessage m,
                         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(I_OverlayMessage m,
                       I_LogicalAddress destla)
Sends the message unicast over the overlay to the destination.

sendFlood

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

receive

public I_OverlayMessage receive()
                         throws java.io.InterruptedIOException
Receive a message. This can only be used if no object implementing I_CallBack 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)
                  throws java.net.SocketException
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().