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.commonapi
Class PastryEndpoint

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

All Implemented Interfaces:
  Endpoint, NodeHandleReader

    public class PastryEndpoint

extends PastryAppl
implements Endpoint

This class serves as gluecode, which allows applications written for the common API to work with pastry.

Version:
  $Id: PastryEndpoint.java 4143 2008-03-06 21:13:55Z jeffh $
Author:
  Alan Mislove, Peter Druschel

Field Summary
`protected Application` | `application`

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

Constructor Summary
`PastryEndpoint(PastryNode pn, Application application, java.lang.String instance, boolean register)` Constructor.
`PastryEndpoint(PastryNode pn, Application application, java.lang.String instance, int address, boolean register)` Constructor.

Method Summary
`NodeHandle` | `coalesce(NodeHandle newHandle)`
`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.
`int` | `getAppId()`
`MessageDeserializer` | `getDeserializer()` Returns the deserializer.
`Environment` | `getEnvironment()` Returns the environment.
`Id` | `getId()` Returns this node's id, which is its identifier in the namespace.
`java.lang.String` | `getInstance()` Returns a unique instance name of this endpoint, sort of a mailbox name for this application.
`NodeHandle` | `getLocalNodeHandle()` Returns a handle to the local node below this endpoint.
`void` | `leafSetChange(NodeHandle nh, boolean wasAdded)` Called by pastry when the leaf set changes.
`NodeHandleSet` | `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.
`NodeHandleSet` | `neighborSet(int num)` This method produces an unordered list of nodehandles that are neighbors of the local node in the ID space.
`java.util.List` | `networkNeighbors(int num)` Returns an ordered list of the nearest known neighbors.
`void` | `process(Executable task, Continuation command)` Schedules a job for processing on the dedicated processing thread.
`int` | `proximity(NodeHandle nh)` This replaces NodeHandle.proximity(), so that you don't have to have a "coalesced" NodeHandle.
`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.
`Id` | `readId(InputBuffer buf, short type)` To use a more efficient serialization format than Java Serialization
`IdRange` | `readIdRange(InputBuffer buf)` To use Raw Serialization
`NodeHandle` | `readNodeHandle(InputBuffer buf)` To use Raw Serialization
`NodeHandleSet` | `readNodeHandleSet(InputBuffer buf, short type)`
`void` | `receiveMessage(Message msg)` Called by pastry to deliver a message to this client.
`NodeHandleSet` | `replicaSet(Id id, int maxRank)` This method returns an ordered set of nodehandles on which replicas of the object with key can be stored.
`NodeHandleSet` | `replicaSet(Id id, int maxRank, NodeHandle root, NodeHandleSet set)` This methods returns an ordered set of nodehandles on which replicas of an object with a given id can be stored.
`MessageReceipt` | `route(Id key, Message msg, NodeHandle hint)` This operation forwards a message towards the root of key.
`MessageReceipt` | `route(Id key, Message msg, NodeHandle hint, DeliveryNotification deliverAckToMe)` This method makes an attempt to route the message to the root of the given id.
`MessageReceipt` | `route(Id key, RawMessage msg, NodeHandle hint)` This duplication of the above code is to make a fast path for the RawMessage.
`MessageReceipt` | `route(Id key, RawMessage msg, NodeHandle hint, DeliveryNotification deliverAckToMe)`
`boolean` | `routingConsistentFor(Id id)` Can we guarantee that this id is currently ours, and routing will be consistent? Note that this has some real timing implications, so don't cache the returned value.
`CancellableTask` | `scheduleMessage(Message message, long delay)` Schedules a message to be delivered to this application after the provided number of milliseconds.
`CancellableTask` | `scheduleMessage(Message message, long delay, long period)` Schedules a message to be delivered to this application every period number of milliseconds, after delay number of miliseconds have passed.
`CancellableTask` | `scheduleMessageAtFixedRate(Message msg, long delay, long period)` Schedule the specified message for repeated fixed-rate delivery to the local node, beginning after the specified delay.
`void` | `setConsistentRouting(boolean val)` default value is true Consistent routing causes RouteMessages to be dropped if we are not sure that we are responsible for our current id range.
`void` | `setDeserializer(MessageDeserializer md)` To use a more efficient serialization format than Java Serialization
`void` | `setSendOptions(java.util.Map<java.lang.String,java.lang.Object> options)` Uses these options as defaults.
`java.lang.String` | `toString()`

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

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

Methods inherited from interface rice.p2p.commonapi.Endpoint
`accept, connect, register`

Field Detail

### application

    protected Application application

Constructor Detail

### PastryEndpoint

    public PastryEndpoint(PastryNode pn,
                          Application application,
                          java.lang.String instance,
                          boolean register)

  Constructor.

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

### PastryEndpoint

    public PastryEndpoint(PastryNode pn,
                          Application application,
                          java.lang.String instance,
                          int address,
                          boolean register)

  Constructor.

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

Method Detail

### getId

    public Id getId()

  Returns this node's id, which is its identifier in the namespace.

  Specified by:
    `getId` in interface `Endpoint`
  Returns:
    The local node's id

### route

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

  Specified by:
    `route` in interface `Endpoint`
  Parameters:
    `key` - the key
    `msg` - the message to deliver.
    `hint` - the hint

### route

    public MessageReceipt route(Id key,
                                Message msg,
                                NodeHandle hint,
                                DeliveryNotification deliverAckToMe)

  Description copied from interface: `Endpoint`
  This method makes an attempt to route the message to the root of the given id. The hint handle will be the first hop in the route. If the id field is null, then the message is routed directly to the given node, and delivers the message there. If the hint field is null, then this method makes an attempt to route the message to the root of the given id. Note that one of the id and hint fields can be null, but not both.

  Specified by:
    `route` in interface `Endpoint`
  Parameters:
    `key` - The destination Id of the message.
    `msg` - The message to deliver
    `hint` - The first node to send this message to, optional
    `deliverAckToMe` - notified when the message is sent
  Returns:
    can cancel the request

### route

    public MessageReceipt route(Id key,
                                RawMessage msg,
                                NodeHandle hint)

  This duplication of the above code is to make a fast path for the RawMessage. Though the codeblock looks identical, it is acually calling a different PEM constructor.

  Specified by:
    `route` in interface `Endpoint`

### route

    public MessageReceipt route(Id key,
                                RawMessage msg,
                                NodeHandle hint,
                                DeliveryNotification deliverAckToMe)

  Specified by:
    `route` in interface `Endpoint`

### scheduleMessage

    public CancellableTask scheduleMessage(Message message,
                                           long delay)

  Schedules a message to be delivered to this application after the provided number of milliseconds.

  Specified by:
    `scheduleMessage` in interface `Endpoint`
  Parameters:
    `message` - The message to be delivered
    `delay` - The number of milliseconds to wait before delivering the message

### scheduleMessage

    public CancellableTask scheduleMessage(Message message,
                                           long delay,
                                           long period)

  Schedules a message to be delivered to this application every period number of milliseconds, after delay number of miliseconds have passed.

  Specified by:
    `scheduleMessage` in interface `Endpoint`
  Parameters:
    `message` - The message to be delivered
    `delay` - The number of milliseconds to wait before delivering the fist message
    `delay` - The number of milliseconds to wait before delivering subsequent messages

### scheduleMessageAtFixedRate

    public CancellableTask scheduleMessageAtFixedRate(Message msg,
                                                      long delay,
                                                      long period)

  Schedule the specified message for repeated fixed-rate delivery to the local node, beginning after the specified delay. Subsequent executions take place at approximately regular intervals, separated by the specified period.

  Specified by:
    `scheduleMessageAtFixedRate` in interface `Endpoint`
  Parameters:
    `msg` - a message that will be delivered to the local node after the specified delay
    `delay` - time in milliseconds before message is to be delivered
    `period` - time in milliseconds between successive message deliveries
  Returns:
    the scheduled event object; can be used to cancel the message

### localLookup

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

  Specified by:
    `localLookup` in interface `Endpoint`
  Parameters:
    `key` - the message's key
    `num` - the maximal number of next hops nodes requested
    `safe` -
  Returns:
    the nodehandle set

### neighborSet

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

  Specified by:
    `neighborSet` in interface `Endpoint`
  Parameters:
    `num` - the maximal number of nodehandles requested
  Returns:
    the nodehandle set

### replicaSet

    public NodeHandleSet replicaSet(Id id,
                                    int maxRank)

  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.

  Specified by:
    `replicaSet` in interface `Endpoint`
  Parameters:
    `key` - the key
    `max_rank` - the maximal number of nodehandles returned
  Returns:
    the replica set

### replicaSet

    public NodeHandleSet replicaSet(Id id,
                                    int maxRank,
                                    NodeHandle root,
                                    NodeHandleSet set)

  This methods returns an ordered set of nodehandles on which replicas of an object with a given id can be stored. The call returns nodes up to and including a node with maxRank. This call also allows the application to provide a remote "center" node, as well as other nodes in the vicinity.

  Specified by:
    `replicaSet` in interface `Endpoint`
  Parameters:
    `id` - The object's id.
    `maxRank` - The number of desired replicas.
    `handle` - The root handle of the remove set
    `set` - The set of other nodes around the root handle

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

  Specified by:
    `range` in interface `Endpoint`
  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 0Returns:
    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.

  Specified by:
    `range` in interface `Endpoint`
  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

### getLocalNodeHandle

    public NodeHandle getLocalNodeHandle()

  Returns a handle to the local node below this endpoint.

  Specified by:
    `getLocalNodeHandle` in interface `Endpoint`
  Returns:
    A NodeHandle referring to the local node.

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

### enrouteMessage

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

  Description copied from class: `PastryAppl`
  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.

  Overrides:
    `enrouteMessage` in class `PastryAppl`
  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)

  Description copied from class: `PastryAppl`
  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.

### process

    public void process(Executable task,
                        Continuation command)

  Schedules a job for processing on the dedicated processing thread. CPU intensive jobs, such as encryption, erasure encoding, or bloom filter creation should never be done in the context of the underlying node's thread, and should only be done via this method.

  Specified by:
    `process` in interface `Endpoint`
  Parameters:
    `task` - The task to run on the processing thread
    `command` - The command to return the result to once it's done

### getInstance

    public java.lang.String getInstance()

  Returns a unique instance name of this endpoint, sort of a mailbox name for this application.

  Specified by:
    `getInstance` in interface `Endpoint`
  Returns:
    The unique instance name of this application

### getEnvironment

    public Environment getEnvironment()

  Description copied from interface: `Endpoint`
  Returns the environment. This allows the nodes to be virtualized within the JVM

  Specified by:
    `getEnvironment` in interface `Endpoint`
  Returns:
    the environment for this node/app.

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

### setDeserializer

    public void setDeserializer(MessageDeserializer md)

  Description copied from interface: `Endpoint`
  To use a more efficient serialization format than Java Serialization

  Specified by:
    `setDeserializer` in interface `Endpoint`
  Overrides:
    `setDeserializer` in class `PastryAppl`

### getDeserializer

    public MessageDeserializer getDeserializer()

  Description copied from interface: `Endpoint`
  Returns the deserializer. The default deserializer can deserialize rice.p2p.util.JavaSerializedMessage

  Specified by:
    `getDeserializer` in interface `Endpoint`
  Overrides:
    `getDeserializer` in class `PastryAppl`
  Returns:

### readId

    public Id readId(InputBuffer buf,
                     short type)
              throws java.io.IOException

  Description copied from interface: `Endpoint`
  To use a more efficient serialization format than Java Serialization

  Specified by:
    `readId` in interface `Endpoint`
  Throws:
    `java.io.IOException`

### readNodeHandle

    public NodeHandle readNodeHandle(InputBuffer buf)
                              throws java.io.IOException

  Description copied from interface: `NodeHandleReader`
  To use Raw Serialization

  Specified by:
    `readNodeHandle` in interface `NodeHandleReader`
  Returns:
  Throws:
    `java.io.IOException`

### readIdRange

    public IdRange readIdRange(InputBuffer buf)
                        throws java.io.IOException

  Description copied from interface: `Endpoint`
  To use Raw Serialization

  Specified by:
    `readIdRange` in interface `Endpoint`
  Returns:
  Throws:
    `java.io.IOException`

### coalesce

    public NodeHandle coalesce(NodeHandle newHandle)

  Specified by:
    `coalesce` in interface `NodeHandleReader`

### readNodeHandleSet

    public NodeHandleSet readNodeHandleSet(InputBuffer buf,
                                           short type)
                                    throws java.io.IOException

  Specified by:
    `readNodeHandleSet` in interface `Endpoint`
  Throws:
    `java.io.IOException`

### networkNeighbors

    public java.util.List networkNeighbors(int num)

  Description copied from interface: `Endpoint`
  Returns an ordered list of the nearest known neighbors. Note that proximity is usually an estimate, and can quickly become stale.

  Specified by:
    `networkNeighbors` in interface `Endpoint`
  Returns:
    List of NodeHandle

### destroy

    public void destroy()

  Description copied from class: `PastryAppl`
  Called when PastryNode is destroyed. Can be overloaded by applications.

  Overrides:
    `destroy` in class `PastryAppl`

### proximity

    public int proximity(NodeHandle nh)

  Description copied from interface: `Endpoint`
  This replaces NodeHandle.proximity(), so that you don't have to have a "coalesced" NodeHandle.

  Specified by:
    `proximity` in interface `Endpoint`
  Returns:

### getAppId

    public int getAppId()

### setConsistentRouting

    public void setConsistentRouting(boolean val)

  Description copied from interface: `Endpoint`
  default value is true Consistent routing causes RouteMessages to be dropped if we are not sure that we are responsible for our current id range. If you set this to false, you will be delivered messages to forward() and deliver() even if there is possible inconsistent routing. (The overlay still does it's best to deliver the RouteMessage to the proper key, but some protocols can guarantee consistency, for example by using leases between nodes) Note that when true, the overlay never purposely drops messages routed with a null key: endpoint.deliver(null, msg, targetNodeHandle) // will be delivered regardless of consistency

  Specified by:
    `setConsistentRouting` in interface `Endpoint`

### deliverWhenNotReady

    public boolean deliverWhenNotReady()

  Description copied from class: `PastryAppl`
  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().

  Overrides:
    `deliverWhenNotReady` in class `PastryAppl`
  Returns:
    false unless the node is a service

### routingConsistentFor

    public boolean routingConsistentFor(Id id)

  Description copied from interface: `Endpoint`
  Can we guarantee that this id is currently ours, and routing will be consistent? Note that this has some real timing implications, so don't cache the returned value. Note that it will always return always returns false if you are not the root of the id.

  Specified by:
    `routingConsistentFor` in interface `Endpoint`
  Returns:
    true if routing consistency can currently be guaranteed for this

### setSendOptions

    public void setSendOptions(java.util.Map<java.lang.String,java.lang.Object> options)

  Description copied from interface: `Endpoint`
  Uses these options as defaults.

  Specified by:
    `setSendOptions` in interface `Endpoint`

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.