Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Rice Pastry API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## rice.pastry.client
Class CommonAPIAppl

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

Direct Known Subclasses:
  RegrTestApp

    public abstract class CommonAPIAppl

extends PastryAppl

CommonAPIAppl is an abstract class that all new applications should extend. It provides the common KBR API defined in "Towards a Common API for Structured Peer-to-Peer Overlays." Frank Dabek, Ben Zhao, Peter Druschel, John Kubiatowicz and Ion Stoica. In Proceedings of the 2nd International Workshop on Peer-to-peer Systems (IPTPS'03) , Berkeley, CA, February 2003.

Version:
  $Id: CommonAPIAppl.java 3801 2007-07-18 15:04:40Z jeffh $
Author:
  Peter Druschel

Field Summary

Fields inherited from class rice.pastry.client.PastryAppl
`address, deserializer, instance, logger, options, receiver, thePastryNode`

Constructor Summary
`CommonAPIAppl(PastryNode pn)` Constructor.
`CommonAPIAppl(PastryNode pn, java.lang.String instance)` Constructor.

Method Summary
`abstract void` | `deliver(Id key, Message msg)` Called by pastry when a message arrives for this application.
`void` | `forward(RouteMessage msg)` Called by pastry when a message is enroute and is passing through this node.
`void` | `leafSetChange(NodeHandle nh, boolean wasAdded)` Called by pastry when the leaf set changes.
`NodeSet` | `localLookup(Id key, int num, boolean safe)` This method produces a list of nodes that can be used as next hops on a route towards key, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken.
`void` | `messageForAppl(Message msg)` Called by pastry when a message arrives for this application.
`NodeSet` | `neighborSet(int num)` This method produces an unordered list of nodehandles that are neighbors of the local node in the ID space.
`void` | `notifyReady()` Invoked when the Pastry node has joined the overlay network and is ready to send and receive messages
`IdRange` | `range(NodeHandle n, int r, Id key)` This method provides information about ranges of keys for which the node n is currently a r-root.
`IdRange` | `range(NodeHandle n, int r, Id key, boolean cumulative)` This method provides information about ranges of keys for which the node n is currently a r-root.
`void` | `receiveMessage(Message msg)` Called by pastry to deliver a message to this client.
`NodeSet` | `replicaSet(Id key, int max_rank)` This method returns an ordered set of nodehandles on which replicas of the object with key can be stored.
`void` | `route(Id key, Message msg, NodeHandle hint)` This operation forwards a message towards the root of key.
`void` | `update(NodeHandle nh, boolean joined)` Called by pastry when the neighbor set changes.

Methods inherited from class rice.pastry.client.PastryAppl
`accept, canReceiveSocket, connect, deliverWhenNotReady, destroy, enrouteMessage, finishReceiveSocket, getAddress, getDeserializer, getLeafSet, getNodeHandle, getNodeId, getRoutingTable, isClosest, receiveMessageInternal, register, routeMsg, routeMsg, routeMsgDirect, routeSetChange, setDeserializer`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CommonAPIAppl

    public CommonAPIAppl(PastryNode pn)

  Constructor.

  Parameters:
    `pn` - the pastry node that the application attaches to.

### CommonAPIAppl

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

  Constructor.

  Parameters:
    `pn` - the pastry node that the application attaches to.

Method Detail

### route

    public void route(Id key,
                      Message msg,
                      NodeHandle hint)

  This operation forwards a message towards the root of key. The optional hint argument specifies a node that should be used as a first hop in routing the message. A good hint, e.g. one that refers to the key's current root, can result in the message being delivered in one hop; a bad hint adds at most one extra hop to the route. Either K or hint may be NULL, but not both. The operation provides a best-effort service: the message may be lost, duplicated, corrupted, or delayed indefinitely.

  Parameters:
    `key` - the key
    `msg` - the message to deliver.
    `hint` - the hint

### localLookup

    public NodeSet localLookup(Id key,
                               int num,
                               boolean safe)

  This method produces a list of nodes that can be used as next hops on a route towards key, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken. If safe is true, the expected fraction of faulty nodes in the list is guaranteed to be no higher than the fraction of faulty nodes in the overlay; if false, the set may be chosen to optimize performance at the expense of a potentially higher fraction of faulty nodes. This option allows applications to implement routing in overlays with byzantine node failures. Implementations that assume fail-stop behavior may ignore the safe argument. The fraction of faulty nodes in the returned list may be higher if the safe parameter is not true because, for instance, malicious nodes have caused the local node to build a routing table that is biased towards malicious nodes~\cite{Castro02osdi}.

  Parameters:
    `key` - the message's key
    `num` - the maximal number of next hops nodes requested
    `safe` -
  Returns:
    the nodehandle set

### neighborSet

    public NodeSet neighborSet(int num)

  This method produces an unordered list of nodehandles that are neighbors of the local node in the ID space. Up to num node handles are returned.

  Parameters:
    `num` - the maximal number of nodehandles requested
  Returns:
    the nodehandle set

### replicaSet

    public NodeSet replicaSet(Id key,
                              int max_rank)

  This method returns an ordered set of nodehandles on which replicas of the object with key can be stored. The call returns nodes with a rank up to and including max_rank. If max_rank exceeds the implementation's maximum replica set size, then its maximum replica set is returned. The returned nodes may be used for replicating data since they are precisely the nodes which become roots for the key when the local node fails.

  Parameters:
    `key` - the key
    `max_rank` - the maximal number of nodehandles returned
  Returns:
    the replica set

### range

    public IdRange range(NodeHandle n,
                         int r,
                         Id key,
                         boolean cumulative)

  This method provides information about ranges of keys for which the node n is currently a r-root. The operations returns null if the range could not be determined. It is an error to query the range of a node not present in the neighbor set as returned by the update upcall or the neighborSet call. Some implementations may have multiple, disjoint ranges of keys for which a given node is responsible (Pastry has two). The parameter key allows the caller to specify which range should be returned. If the node referenced by n is the r-root for key, then the resulting range includes key. Otherwise, the result is the nearest range clockwise from key for which n is responsible.

  Parameters:
    `n` - nodeHandle of the node whose range is being queried
    `r` - the rank
    `key` - the key
    `cumulative` - if true, returns ranges for which n is an i-root for 0 Returns:
    the range of keys, or null if range could not be determined for the given node and rank

### range

    public IdRange range(NodeHandle n,
                         int r,
                         Id key)

  This method provides information about ranges of keys for which the node n is currently a r-root. The operations returns null if the range could not be determined. It is an error to query the range of a node not present in the neighbor set as returned by the update upcall or the neighborSet call. Some implementations may have multiple, disjoint ranges of keys for which a given node is responsible (Pastry has two). The parameter key allows the caller to specify which range should be returned. If the node referenced by n is the r-root for key, then the resulting range includes key. Otherwise, the result is the nearest range clockwise from key for which n is responsible.

  Parameters:
    `n` - nodeHandle of the node whose range is being queried
    `r` - the rank
    `key` - the key
  Returns:
    the range of keys, or null if range could not be determined for the given node and rank

### deliver

    public abstract void deliver(Id key,
                                 Message msg)

  Called by pastry when a message arrives for this application.

  Parameters:
    `msg` - the message that is arriving.

### forward

    public void forward(RouteMessage msg)

  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.

### update

    public void update(NodeHandle nh,
                       boolean joined)

  Called by pastry when the neighbor 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

  Overrides:
    `notifyReady` in class `PastryAppl`

### messageForAppl

    public final void messageForAppl(Message msg)

  Description copied from class: `PastryAppl`
  Called by pastry when a message arrives for this application.

  Specified by:
    `messageForAppl` in class `PastryAppl`
  Parameters:
    `msg` - the message that is arriving.

### leafSetChange

    public final void leafSetChange(NodeHandle nh,
                                    boolean wasAdded)

  Called by pastry when the leaf set changes.

  Overrides:
    `leafSetChange` in class `PastryAppl`
  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.

### receiveMessage

    public void receiveMessage(Message msg)

  Called by pastry to deliver a message to this client. Not to be overridden.

  Overrides:
    `receiveMessage` in class `PastryAppl`
  Parameters:
    `msg` - the message that is arriving.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Rice Pastry API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 - Rice Pastry.