org.kth.dks
Interface DKSInterface

All Known Subinterfaces:

DKSDHTInterface, DKSDHTVisualizationInterface, DKSMCastDHTInterface

All Known Implementing Classes:

DKSDHTImpl, DKSImpl, DKSMCastDHTImpl

public interface DKSInterface

DKSInterface represents a basic routing interface which essentially lets DKS nodes join and leave the system. It also provides a basic operation to find the node responsible for a given identifier Note that keys are represented by long (64 bit) integers in this interface. It is up to other services using this interface to translate application specific keys to this representation.

Method Summary

boolean	addMsgHandler(DKSMessage msg, java.lang.Object handlerObject, java.lang.String methodName) Registers a handler for a DKSMessage.
void	broadcast(DKSObject message) Broadcasts the given message.
void	broadcastRestricted(DKSObject message, long startId, long endId) Broadcasts the given message.
void	create() Called by the first node in a ring, this will create a new DKS network containing one node only
DKSRef	findResponsible(long identifier) Will find the DKS node that is responsible for the given identifier
DKSRef	getDKSRef() Returns the DKSRef associated to this DKS node
java.lang.String	getDKSURL() Returns the DKSURL (stringified DKSRef) used by this DKS node
void	join(DKSRef existingnodeAddress) Adds a new node to the network managed by the local DKS implementation.
void	leave() Disconnect the local node from the network.
void	logLevel(int level) Set the logging level
DKSObject	route(long identifier, DKSObject payload) Will route a message the DKS node that is responsible for the given identifier, and call routeCallback() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller
void	routeAsync(long identifier, DKSObject payload) Will route a message the DKS node that is responsible for the given identifier, and call routeCallbackAsync() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller
void	routeAsyncFrom(long identifier, DKSObject payload, DKSRef firstNode) Will route a message, starting at firstNode, the DKS node that is responsible for the given identifier, and call routeCallbackAsync() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller.
void	send(DKSRef target, DKSMessage message) Sends a DKSMessage to a DKS node
void	unregisterNode() Every object implementing this interface gets registered in a ConnectionManager, this method this method unregisters the object in the ConnectionManager.

Method Detail

join

void join(DKSRef existingnodeAddress)
          throws DKSTooManyRestartJoins,
                 DKSIdentifierAlreadyTaken,
                 DKSRefNoResponse

Adds a new node to the network managed by the local DKS implementation.

Parameters:

nodeId - The unique DKS node identifier (key) for the new node.

nodeAddress - The location of the new node on the physical underlying network.

Throws:

DKSTooManyRestartJoins

DKSIdentifierAlreadyTaken

DKSRefNoResponse

create

void create()

Called by the first node in a ring, this will create a new DKS network containing one node only

Parameters:

existingnodeAddress - DKSOverlayAddress

logLevel

void logLevel(int level)

Set the logging level

Parameters:

level - int, 0 means no logging, 1 means debug prints, 2 means XML dumps

leave

void leave()

Disconnect the local node from the network.

findResponsible

DKSRef findResponsible(long identifier)

Will find the DKS node that is responsible for the given identifier

Parameters:

identifier - whose responsible node is being queried for

Returns:

DKSRef reference to the responsible node

route

DKSObject route(long identifier,
                DKSObject payload)

Will route a message the DKS node that is responsible for the given identifier, and call routeCallback() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller

Parameters:

identifier - whose responsible node being routed to

payload - to be sent to the responsible node

Returns:

DKSOBject payload sent back by the responsible node

See Also:

DKSAppInterface

routeAsync

void routeAsync(long identifier,
                DKSObject payload)

Will route a message the DKS node that is responsible for the given identifier, and call routeCallbackAsync() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller

Parameters:

identifier - whose responsible node being routed to

payload - to be sent to the responsible node

See Also:

DKSAppInterface

routeAsyncFrom

void routeAsyncFrom(long identifier,
                    DKSObject payload,
                    DKSRef firstNode)

Will route a message, starting at firstNode, the DKS node that is responsible for the given identifier, and call routeCallbackAsync() at that node and give it the payload, upon which the responsible node will respond with a payload which is returned to the caller.

Parameters:

identifier - long

payload - DKSObject

firstNode - DKSRef

broadcast

void broadcast(DKSObject message)

Broadcasts the given message.

broadcastRestricted

void broadcastRestricted(DKSObject message,
                         long startId,
                         long endId)

Broadcasts the given message.

getDKSURL

java.lang.String getDKSURL()

Returns the DKSURL (stringified DKSRef) used by this DKS node

Returns:

String

See Also:

DKSRef

getDKSRef

DKSRef getDKSRef()

Returns the DKSRef associated to this DKS node

Returns:

DKSRef

See Also:

DKSRef

unregisterNode

void unregisterNode()

Every object implementing this interface gets registered in a ConnectionManager, this method this method unregisters the object in the ConnectionManager. This method needs to be called especially if another object of this type is to be instantiated with the same DKSNetAddress (overlay identity)

send

void send(DKSRef target,
          DKSMessage message)

Sends a DKSMessage to a DKS node

Parameters:

target - a DKSRef to a node in the system

message - a DKSMessage

addMsgHandler

boolean addMsgHandler(DKSMessage msg,
                      java.lang.Object handlerObject,
                      java.lang.String methodName)

Registers a handler for a DKSMessage. DKS will invoke the handler whenever a DKSMessage of that type is received.

Parameters:

msg - Some object which is a subclass of DKSMessage

handlerObject - Object whose method will be invoked upon receipt of a message of type DKSMessage

methodName - full case sensitive of the method to be invoked(without paranthesis). The method has a predefined signature as described in the following example. Example: if the method name is "handleStore", there should a method in handlerObject with the signature
public void handleStore(DKSRef sender, msgClass msg)
, where msgClass is the tye of the parameter msg.

Returns:

true if registration succeeded, or false if it failed (which can occur if a DKSMessage with the same internal string exists).