rice.pastry.client
Class PastryAppl

java.lang.Object
  rice.pastry.client.PastryAppl

All Implemented Interfaces:

MessageReceiver

Direct Known Subclasses:

CommonAPIAppl, HelloWorldApp, PastryEndpoint, PeriodicLeafSetProtocol, Ping, PingClient, StandardJoinProtocol

public abstract class PastryAppl

extends java.lang.Object

implements MessageReceiver

A PastryAppl is an abstract class that every Pastry application extends. This is the external Pastry API.

Version:

$Id: PastryAppl.java 3041 2006-02-07 13:31:33Z jeffh $

Author:

Peter Druschel

Field Summary

protected Address	address
protected java.lang.String	instance
protected Logger	logger
protected PastryNode	thePastryNode

Constructor Summary

PastryAppl(PastryNode pn)
Constructor.

PastryAppl(PastryNode pn, int port)
Constructor.

PastryAppl(PastryNode pn, java.lang.String instance)
Constructor.

PastryAppl(PastryNode pn, java.lang.String instance, Address address)

Method Summary

boolean	deliverWhenNotReady() Instructs the MessageDispatch how to behave when the PastryNode is not ready.
void	destroy() Called when PastryNode is destroyed.
boolean	enrouteMessage(Message msg, Id key, NodeHandle nextHop, SendOptions opt) Called by pastry when a message is enroute and is passing through this node.
Address	getAddress() Returns the address of this application.
abstract Credentials	getCredentials() Returns the credentials of this application.
LeafSet	getLeafSet() Called by a layered Pastry application to obtain a copy of the leaf set.
NodeHandle	getNodeHandle() Gets the handle of the Pastry node associated with this client
NodeId	getNodeId() Gets the node id associated with this client.
RoutingTable	getRoutingTable() Called by a layered Pastry application to obtain a copy of the routing table.
boolean	isClosest(NodeId key) Called by the layered Pastry application to check if the local pastry node is the one that is currently closest to the object key id.
void	leafSetChange(NodeHandle nh, boolean wasAdded) Called by pastry when the leaf set changes.
abstract void	messageForAppl(Message msg) Called by pastry when a message arrives for this application.
void	notifyReady() Invoked when the Pastry node has joined the overlay network and is ready to send and receive messages As of FreePastry 1.4.1, replaced by PastryNode Observer pattern.
void	receiveMessage(Message msg) Called by pastry to deliver a message to this client.
protected void	register()
void	registerReceiver(Credentials cred, Address addr, MessageReceiver mr) Registers a message receiver with the pastry node.
void	routeMsg(Id key, Message msg, Credentials cred, SendOptions opt) Routes a message to the live node D with nodeId numerically closest to key (at the time of delivery).
boolean	routeMsgDirect(NodeHandle dest, Message msg, Credentials cred, SendOptions opt) Sends a message to the Pastry node identified by dest.
void	routeSetChange(NodeHandle nh, boolean wasAdded) Called by pastry when the route set changes.
void	sendMessage(Message msg) Sends a message directly to the local pastry node.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

instance

protected java.lang.String instance

thePastryNode

protected PastryNode thePastryNode

address

protected Address address

logger

protected Logger logger

Constructor Detail

PastryAppl

public PastryAppl(PastryNode pn)

Constructor.

Parameters:

pn - the pastry node that client will attach to.

PastryAppl

public PastryAppl(PastryNode pn,
                  java.lang.String instance)

Constructor. This constructor will perform the same tasks as the above constructor, but will also create a Pastry address for this application, which is dependent upon the given instance name and the class name.

Parameters:

pn - the pastry node that client will attach to.

instance - The instance name of this appl.

PastryAppl

public PastryAppl(PastryNode pn,
                  java.lang.String instance,
                  Address address)

PastryAppl

public PastryAppl(PastryNode pn,
                  int port)

Constructor. This constructor will perform the same tasks as the above constructor, but will also create a Pastry address for this application, using the specified port.

Parameters:

pn - the pastry node that client will attach to.

instance - The instance name of this appl.

Method Detail

register

protected void register()

getAddress

public Address getAddress()

Returns the address of this application.

Returns:

the address.

registerReceiver

public final void registerReceiver(Credentials cred,
                                   Address addr,
                                   MessageReceiver mr)

Registers a message receiver with the pastry node. This binds the given address to a message receiver. This binding is certified by the given credentials. Messages that are delivered to this node with the given address as a destination are forwarded to the supplied receiver.

Parameters:

cred - credentials which verify the binding

addr - an address

mr - a message receiver which will be bound the address.

sendMessage

public final void sendMessage(Message msg)

Sends a message directly to the local pastry node.

Parameters:

msg - a message.

receiveMessage

public void receiveMessage(Message msg)

Called by pastry to deliver a message to this client.

Specified by:

receiveMessage in interface MessageReceiver

Parameters:

msg - the message that is arriving.

getNodeId

public final NodeId getNodeId()

Gets the node id associated with this client.

Returns:

the node id.

getNodeHandle

public NodeHandle getNodeHandle()

Gets the handle of the Pastry node associated with this client

Returns:

the node handle

routeMsgDirect

public boolean routeMsgDirect(NodeHandle dest,
                              Message msg,
                              Credentials cred,
                              SendOptions opt)

Sends a message to the Pastry node identified by dest. If that node has failed or no point-to-point connection can be established to the node from the local node in the Internet, the operation fails. Note that in this case, it may still be possible to send the message to that node using routeMsg.

Parameters:

dest - the destination node

msg - the message to deliver.

cred - credentials that verify the authenticity of the message.

opt - send options that describe how the message is to be routed.

routeMsg

public void routeMsg(Id key,
                     Message msg,
                     Credentials cred,
                     SendOptions opt)

Routes a message to the live node D with nodeId numerically closest to key (at the time of delivery). The message is delivered to the application with address addr at D, and at each Pastry node encountered along the route to D.

Parameters:

key - the key

msg - the message to deliver.

cred - credentials that verify the authenticity of the message.

opt - send options that describe how the message is to be routed.

getLeafSet

public LeafSet getLeafSet()

Called by a layered Pastry application to obtain a copy of the leaf set. The leaf set contains the nodeId to IP address binding of the l/2 nodes with numerically closest counterclockwise and the l/2 nodes with numerically closest clockwise nodeIds, relatively to the local node's id.

Returns:

the local node's leaf set

getRoutingTable

public RoutingTable getRoutingTable()

Called by a layered Pastry application to obtain a copy of the routing table. The routing table contains the nodeId to IP address bindings of R nodes that share the local node's id in the first n digits, and differ in the n+1th digit, for 0 <= n <= ceiling(log_2^b N), where N is the total number of currently live nodes in the Pastry network. The routing table may be incomplete, may contain nodes that cannot be reached from the local node or have failed, and the table may change at any time.

isClosest

public boolean isClosest(NodeId key)

Called by the layered Pastry application to check if the local pastry node is the one that is currently closest to the object key id.

Parameters:

key - the object key id

Returns:

true if the local node is currently the closest to the key.

getCredentials

public abstract Credentials getCredentials()

Returns the credentials of this application.

Returns:

the credentials.

messageForAppl

public abstract void messageForAppl(Message msg)

Called by pastry when a message arrives for this application.

Parameters:

msg - the message that is arriving.

enrouteMessage

public boolean enrouteMessage(Message msg,
                              Id key,
                              NodeHandle nextHop,
                              SendOptions opt)

Called by pastry when a message is enroute and is passing through this node. If this method is not overridden, the default behaviour is to let the message pass through.

Parameters:

msg - the message that is passing through.

key - the key

nextHop - the default next hop for the message.

opt - the send options the message was sent with.

Returns:

true if the message should be routed, false if the message should be cancelled.

leafSetChange

public void leafSetChange(NodeHandle nh,
                          boolean wasAdded)

Called by pastry when the leaf set changes.

Parameters:

nh - the handle of the node that was added or removed.

wasAdded - true if the node was added, false if the node was removed.

routeSetChange

public void routeSetChange(NodeHandle nh,
                           boolean wasAdded)

Called by pastry when the route set changes.

Parameters:

nh - the handle of the node that was added or removed.

wasAdded - true if the node was added, false if the node was removed.

notifyReady

public void notifyReady()

Invoked when the Pastry node has joined the overlay network and is ready to send and receive messages As of FreePastry 1.4.1, replaced by PastryNode Observer pattern.

deliverWhenNotReady

public boolean deliverWhenNotReady()

Instructs the MessageDispatch how to behave when the PastryNode is not ready. An application can override this method to return true if it wishes to receive messages before Pastry is ready(). Most applications should leave this as false, so that their application does not have inconsistent routing. However Pastry's protocols (such as the join protocol) need to receive messages before pastry is ready(). This is because they are attempting to make pastry ready().

Returns:

false unless the node is a service

destroy

public void destroy()

Called when PastryNode is destroyed. Can be overloaded by applications.