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.p2p.commonapi
Interface Endpoint

All Superinterfaces:
  NodeHandleReader

All Known Implementing Classes:
  GCEndpoint, MultiringEndpoint, PastryEndpoint

    public interface Endpoint

extends NodeHandleReader

Version:
  $Id: Endpoint.java 4654 2009-01-08 16:33:07Z jeffh $
Author:
  Alan Mislove, Peter Druschel

Method Summary
`void` | `accept(AppSocketReceiver receiver)` Set's the acceptor for this application.
`void` | `connect(NodeHandle handle, AppSocketReceiver receiver, int timeout)` Opens a connection to this application on a remote node.
`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.
`boolean` | `isAlive(NodeHandle nh)`
`NodeHandleSet` | `localLookup(Id id, int num, boolean safe)` This call produces a list of nodes that can be used as next hops on a route towards the given id, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken.
`NodeHandleSet` | `neighborSet(int num)` This methods returns an unordered set of nodehandles on which are neighbors of the local node in the id space.
`java.util.List<NodeHandle>` | `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 handle, int rank, Id lkey)` This operation provides information about ranges of keys for which the node is currently a rank-root.
`IdRange` | `range(NodeHandle handle, int rank, Id lkey, boolean cumulative)` This operation provides information about ranges of keys for which the node is currently a rank-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` | `register()` Call this after you have set up your Endpoint: called setDeserializer(), called accept().
`NodeHandleSet` | `replicaSet(Id id, int maxRank)` This method returns an ordered set of nodehandles on which replicas of an object with a given id 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 id, Message message, NodeHandle hint)`
`MessageReceipt` | `route(Id id, Message message, NodeHandle hint, DeliveryNotification deliverAckToMe)`
`MessageReceipt` | `route(Id id, Message message, NodeHandle hint, DeliveryNotification deliverAckToMe, java.util.Map<java.lang.String,java.lang.Object> options)` This method makes an attempt to route the message to the root of the given id.
`MessageReceipt` | `route(Id id, RawMessage message, NodeHandle hint)`
`MessageReceipt` | `route(Id id, RawMessage message, NodeHandle hint, DeliveryNotification deliverAckToMe)`
`MessageReceipt` | `route(Id id, RawMessage message, NodeHandle hint, DeliveryNotification deliverAckToMe, java.util.Map<java.lang.String,java.lang.Object> options)` Same as the other call, but uses the Raw serialization rather than java serialization.
`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 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.
`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.

Methods inherited from interface rice.p2p.commonapi.rawserialization.NodeHandleReader
`coalesce`

Method Detail

### getId

    Id getId()

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

  Returns:
    The local node's id

### route

    MessageReceipt route(Id id,
                         Message message,
                         NodeHandle hint,
                         DeliveryNotification deliverAckToMe,
                         java.util.Map<java.lang.String,java.lang.Object> options)

  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.

  Parameters:
    `id` - The destination Id of the message.
    `message` - 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

    MessageReceipt route(Id id,
                         Message message,
                         NodeHandle hint,
                         DeliveryNotification deliverAckToMe)

### route

    MessageReceipt route(Id id,
                         Message message,
                         NodeHandle hint)

### route

    MessageReceipt route(Id id,
                         RawMessage message,
                         NodeHandle hint,
                         DeliveryNotification deliverAckToMe,
                         java.util.Map<java.lang.String,java.lang.Object> options)

  Same as the other call, but uses the Raw serialization rather than java serialization.

  Parameters:
    `id` -
    `message` -
    `hint` -

### route

    MessageReceipt route(Id id,
                         RawMessage message,
                         NodeHandle hint,
                         DeliveryNotification deliverAckToMe)

### route

    MessageReceipt route(Id id,
                         RawMessage message,
                         NodeHandle hint)

### localLookup

    NodeHandleSet localLookup(Id id,
                              int num,
                              boolean safe)

  This call produces a list of nodes that can be used as next hops on a route towards the given id, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken. If the safe flag is specified, then the fraction of faulty nodes returned is no higher than the fraction of faulty nodes in the overlay.

  Parameters:
    `id` - The destination id.
    `num` - The number of nodes to return.
    `safe` - Whether or not to return safe nodes.

### neighborSet

    NodeHandleSet neighborSet(int num)

  This methods returns an unordered set of nodehandles on which are neighbors of the local node in the id space. Up to num handles are returned. NOTE: This is not the same thing as the neighborhood set as described in some early papers. The if you are looking for the neighborhood set, see localLookup()

  Parameters:
    `num` - The number of desired handle to return.

### replicaSet

    NodeHandleSet replicaSet(Id id,
                             int maxRank)

  This method 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 method is equivalent to calling replicaSet(id, maxRank, getLocalNodeHandle(), neighborSet(Integer.MAX_VALUE));

  Parameters:
    `id` - The object's id.
    `maxRank` - The number of desired replicas.

### replicaSet

    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.

  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

    IdRange range(NodeHandle handle,
                  int rank,
                  Id lkey)
                  throws RangeCannotBeDeterminedException

  This operation provides information about ranges of keys for which the node is currently a rank-root. The operations throws an exception 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 bythe update upcall or the neighborSet call. Certain implementations may return an error if rank is greater than zero. Some protocols may have multiple, disjoint ranges of keys for which a given node is responsible. The parameter lkey allows the caller to specify which region should be returned. If the node referenced by is responsible for key lkey, then the resulting range includes lkey. Otherwise, the result is the nearest range clockwise from lkey for which is responsible.

  Parameters:
    `handle` - The handle whose range to check.
    `rank` - The root rank.
    `lkey` - An "index" in case of multiple ranges.
  Throws:
    `RangeCannotBeDeterminedException`

### range

    IdRange range(NodeHandle handle,
                  int rank,
                  Id lkey,
                  boolean cumulative)
                  throws RangeCannotBeDeterminedException

  This operation provides information about ranges of keys for which the node is currently a rank-root. The operations returns null if the range could not be determined, the range otherwise. It is an error to query the range of a node not present in the neighbor set as returned bythe update upcall or the neighborSet call. Certain implementations may return an error if rank is greater than zero. Some protocols may have multiple, disjoint ranges of keys for which a given node is responsible. The parameter lkey allows the caller to specify which region should be returned. If the node referenced by is responsible for key lkey, then the resulting range includes lkey. Otherwise, the result is the nearest range clockwise from lkey for which is responsible.

  Parameters:
    `handle` - The handle whose range to check.
    `rank` - The root rank.
    `lkey` - An "index" in case of multiple ranges.
    `cumulative` - Whether to return the cumulative or single range
  Throws:
    `RangeCannotBeDeterminedException`

### getLocalNodeHandle

    NodeHandle getLocalNodeHandle()

  Returns a handle to the local node below this endpoint. This node handle is serializable, and can therefore be sent to other nodes in the network and still be valid.

  Returns:
    A NodeHandle referring to the local node.

### scheduleMessage

    CancellableTask scheduleMessage(Message message,
                                    long delay)

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

  Parameters:
    `message` - The message to be delivered
    `delay` - The number of milliseconds to wait before delivering the message

### scheduleMessage

    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.

  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

    CancellableTask scheduleMessageAtFixedRate(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.

  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

### process

    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.

  Parameters:
    `task` - The task to run on the processing thread
    `command` - The command to return the result to once it's done

### getInstance

    java.lang.String getInstance()

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

  Returns:
    The unique instance name of this application

### getEnvironment

    Environment getEnvironment()

  Returns the environment. This allows the nodes to be virtualized within the JVM

  Returns:
    the environment for this node/app.

### accept

    void accept(AppSocketReceiver receiver)

  Set's the acceptor for this application. If no acceptor is set, then when a remote node's application opens a socket here, they will get an *Exception*

  Parameters:
    `receiver` - calls receiveSocket() when a new AppSocket is opened to this application from a remote node. Note that you must call accept() again after each socket is received to properly handle socket backlogging

### connect

    void connect(NodeHandle handle,
                 AppSocketReceiver receiver,
                 int timeout)

  Opens a connection to this application on a remote node. If no acceptor is set, then receiver will get an *Exception*

  Parameters:
    `receiver` - calls receiveSocket() when a new AppSocket is opened to this application on a remote node.

### setDeserializer

    void setDeserializer(MessageDeserializer md)

  To use a more efficient serialization format than Java Serialization

  Parameters:
    `md` -

### getDeserializer

    MessageDeserializer getDeserializer()

  Returns the deserializer. The default deserializer can deserialize rice.p2p.util.JavaSerializedMessage

  Returns:

### setConsistentRouting

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

  Parameters:
    `val` -

### routingConsistentFor

    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. Note that it will always return always returns false if you are not the root of the id.

  Parameters:
    `the` - id to verify
  Returns:
    true if routing consistency can currently be guaranteed for this

### readId

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

  To use a more efficient serialization format than Java Serialization

  Parameters:
    `md` -
  Throws:
    `java.io.IOException`

### networkNeighbors

    java.util.List<NodeHandle> networkNeighbors(int num)

  Returns an ordered list of the nearest known neighbors. Note that proximity is usually an estimate, and can quickly become stale.

  Parameters:
    `num` -
  Returns:
    List of NodeHandle

### readIdRange

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

  To use Raw Serialization

  Parameters:
    `buf` -
  Returns:
  Throws:
    `java.io.IOException`

### readNodeHandleSet

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

  Throws:
    `java.io.IOException`

### readNodeHandle

    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`

### register

    void register()

  Call this after you have set up your Endpoint: called setDeserializer(), called accept().

### proximity

    int proximity(NodeHandle nh)

  This replaces NodeHandle.proximity(), so that you don't have to have a "coalesced" NodeHandle.

  Parameters:
    `nh` -
  Returns:

### isAlive

    boolean isAlive(NodeHandle nh)

### setSendOptions

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

  Uses these options as defaults.

  Parameters:
    `options` -

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.