rice.scribe
Interface IScribe

All Known Implementing Classes:

Scribe

public interface IScribe

Method Summary

boolean	addChild(NodeHandle child, NodeId topicId) Add a node as a child in the children table for a topic.
boolean	anycast(NodeId groupId, MessageAnycast anycastMessage, Credentials cred) An application can create sub-classes of MessageAnycast type of messages and write their own handling functions so as to take care of routing of these messages and also to handle cases where the anycast message reaches an intermediate node where there is no application running to take care of it.
boolean	anycast(NodeId groupID, java.io.Serializable obj, Credentials cred) Anycast to a group/topic.
boolean	create(NodeId groupID, Credentials cred) Creates a group/topic if the credentials are valid.
NodeId	generateTopicId(java.lang.String topicName) Generate a unique id for the topic, which will determine its rendezvous point.
java.util.Vector	getChildren(NodeId topicId) This returns the most current view of the children in this topic's multicast subtree rooted at the local node.
NodeHandle	getParent(NodeId topicId) Returns the local node's parent in this topic's multicast tree.
boolean	join(NodeId groupID, IScribeApp subscriber, Credentials cred) Joins a multicast group/topic.
boolean	join(NodeId groupID, IScribeApp subscriber, Credentials cred, java.io.Serializable obj) Joins a multicast group/topic.
boolean	leave(NodeId groupID, IScribeApp subscriber, Credentials cred) Leaving a multicast group/topic.
boolean	multicast(NodeId groupID, java.io.Serializable obj, Credentials cred) Multicast information to a group/topic.
int	numChildren(NodeId topicId) This returns the number of children in this topic's multicast subtree rooted at the local node.
void	registerApp(IScribeApp app) Registers the IScribeApp to the Scribe substrate.
void	registerScribeObserver(IScribeObserver app) Registers the application that implements the IScribeObserver interface.
boolean	removeChild(NodeHandle child, NodeId topicId) Removes a node as a child from the children table for a topic.
void	scheduleHB() Sends heartbeat messages to this local node's children for all the topics on this local scribe node.
boolean	setParent(NodeHandle parent, NodeId topicId) Sets the parent for the topic specified by topicId.
void	setTreeRepairThreshold(int value) The tree repair event for a particular topic in Scribe is triggered when a node misses a certain treeRepairThreshold number of heartbeat messages from its parent for the topic.

Method Detail

registerApp

public void registerApp(IScribeApp app)

Registers the IScribeApp to the Scribe substrate. This is required for the IScribeApp to get the upcall scribeIsReady() notifying it that the underlying Scribe substrate is ready. The IScribeApp should call create, join, leave, multicast only after they are notified that the underlying Scribe substrate is ready, otherwise these operations fail.

registerScribeObserver

public void registerScribeObserver(IScribeObserver app)

Registers the application that implements the IScribeObserver interface. Whenever a topic is implicitly created, these registered applications would be notified.

Parameters:

app - The application interested in getting notified whenever a topic is implicitly created.

create

public boolean create(NodeId groupID,
                      Credentials cred)

Creates a group/topic if the credentials are valid. Nodes must then join this group in order to get information multicast to it.

Parameters:

cred - The credentials of the entity creating the group

groupID - The ID of the group to be created

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

join

public boolean join(NodeId groupID,
                    IScribeApp subscriber,
                    Credentials cred)

Joins a multicast group/topic. When a node joins a multicast group, it receives all messages multicast to that group.

Parameters:

cred - The credentials of the entity joining the group

groupID - The ID of the group to join to

subscriber - The application joining the group

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

join

public boolean join(NodeId groupID,
                    IScribeApp subscriber,
                    Credentials cred,
                    java.io.Serializable obj)

Joins a multicast group/topic. When a node joins a multicast group, it receives all messages multicast to that group. An application can specify additional data to be sent with the SUBSCRIBE message.

Parameters:

cred - The credentials of the entity joining the group

groupID - The ID of the group to join to

subscriber - The application joining the group

obj - Additional data to be passed with the SUBSCRIBE msg, specific to an application. Should be serializable.

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

leave

public boolean leave(NodeId groupID,
                     IScribeApp subscriber,
                     Credentials cred)

Leaving a multicast group/topic. After a node leaves a group, it will no longer receive messages multicast to this group.

Parameters:

cred - The credentials of the entity leaving the group

groupID - The ID of the group to leave

subscriber - The application leaving the group. Use null if not directly called by an application.

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

multicast

public boolean multicast(NodeId groupID,
                         java.io.Serializable obj,
                         Credentials cred)

Multicast information to a group/topic. Data will be delivered to All nodes that have joined the group. The message will trickle from the root of the multicast tree for the group DOWN the tree, with each node sending this message to its children for the group.

Parameters:

cred - The credentials of the entity multicasting to the group

groupID - The ID of the group to multicast.

obj - The information that is to be multicast. This should be serializable.

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

anycast

public boolean anycast(NodeId groupID,
                       java.io.Serializable obj,
                       Credentials cred)

Anycast to a group/topic. Data will be delivered to 'ANY' one node which has joined the group. The handling of anycast message is left to the application. The applications may do DFS of its subtree to evaluate some predicates to find out a node having desirable properties. The anycast message would be dropped on floor at an intermediate node if there is no application running on it to handle the anycast message.

Parameters:

groupID - The ID of the group to anycast.

obj - The information that is to be included in anycast message. This should be serializable.

cred - The credentials of the entity anycasting to the group.

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

anycast

public boolean anycast(NodeId groupId,
                       MessageAnycast anycastMessage,
                       Credentials cred)

An application can create sub-classes of MessageAnycast type of messages and write their own handling functions so as to take care of routing of these messages and also to handle cases where the anycast message reaches an intermediate node where there is no application running to take care of it.

Parameters:

anycastMessage - The anycast message created by application specific to its needs, can decide how the message is going to be routed in the anycast tree, how the message is going to be handled and so on.

cred - The credentials of the entity anycasting to the group.

Returns:

true if the operation was successful, false if the operation failed because the underlying Scribe substrate was not ready.

scheduleHB

public void scheduleHB()

Sends heartbeat messages to this local node's children for all the topics on this local scribe node. This method should be invoked periodically by the driver with the same frequency in all nodes. In addition to initiating sending of heartbeat messages from this local node, this method also implicitly notifies the local node that it should expect a heartbeat message from its parents for all the topics on this local node. So, if it fails to receive a threshold value of such heartbeat messages from any parent for a particular topic, a tree repair event is triggered for that topic.

setTreeRepairThreshold

public void setTreeRepairThreshold(int value)

The tree repair event for a particular topic in Scribe is triggered when a node misses a certain treeRepairThreshold number of heartbeat messages from its parent for the topic. This threshold value can be set using this method.

Parameters:

value - The value for the treeRepairThreshold.

generateTopicId

public NodeId generateTopicId(java.lang.String topicName)

Generate a unique id for the topic, which will determine its rendezvous point. This is a helper method. Applications can use their own methods to generate TopicId.

Parameters:

topicName - The name of the topic (unique to the local node)

Returns:

the TopicId

getParent

public NodeHandle getParent(NodeId topicId)

Returns the local node's parent in this topic's multicast tree.

Parameters:

topicId - The id of the topic.

Returns:

the parent node.

setParent

public boolean setParent(NodeHandle parent,
                         NodeId topicId)

Sets the parent for the topic specified by topicId.

Parameters:

parent - The new parent for the topic

topicId - the topic for which this parent is set

Returns:

true if operation was successful, false otherwise

getChildren

public java.util.Vector getChildren(NodeId topicId)

This returns the most current view of the children in this topic's multicast subtree rooted at the local node.

Parameters:

topicId - The id of the topic.

Returns:

vector of children nodehandles.

numChildren

public int numChildren(NodeId topicId)

This returns the number of children in this topic's multicast subtree rooted at the local node.

Parameters:

topicId - The id of the topic.

Returns:

the number of children of local node for this topic.

addChild

public boolean addChild(NodeHandle child,
                        NodeId topicId)

Add a node as a child in the children table for a topic.

Parameters:

child - the child to be added

topicId - the topic for which this child is added

Returns:

true if operation was successful, false otherwise

removeChild

public boolean removeChild(NodeHandle child,
                           NodeId topicId)

Removes a node as a child from the children table for a topic.

Parameters:

child - the child to be removed

topicId - the topic for which this child is removed

Returns:

true if operation was successful, false otherwise