rice.scribe
Class Scribe

public class Scribe
extends rice.pastry.client.PastryAppl
implements rice.scribe.IScribe
Version:
$Id: Scribe.java,v 1.21 2002/09/08 01:23:34 druschel Exp $
Author:
Romer Gil
Eric Engineer
Atul Singh
Animesh Nandi
Field Detail

m_apps

protected java.util.Vector m_apps
The set of IScribeApp's that have registered to this Scribe substrate.

m_ready

private boolean m_ready
This flag is set to true when this Scribe substrate is ready. The Scribe substrate is ready when the underlying Pastry Node is ready.

m_topics

public java.util.HashMap m_topics
Set of topics on the local scribe node.

m_treeRepairThreshold

private int m_treeRepairThreshold
The threshold value for triggering tree repair for a topic. Tree repair for a topic is triggered after we have missed this threshold value of heartbeat messages from the parent for the topic. This threshold value can be set using the setTreeRepairThreshold method and its value retreived using the getTreeRepairThreshold method. Default value is 2.

m_distinctChildrenTable

protected java.util.Hashtable m_distinctChildrenTable
Hashtable having mapping from a child -> list of topics for which this child is in local node's children list for that topic. In this way, this table will have only distinct children and for each child we have the list of topics for which it is a child. Used to identify distinct chidren when sending HeartBeat messages, so that we dont send a node multiple HeartBeat messages when it is child for more than one topic.

m_distinctParentTable

protected java.util.Hashtable m_distinctParentTable
Hashtable having mapping from a parent node -> list of topics for which the parent node is local node's parent in the corresponding multicast tree for that topic. Whenever local node receives a HeartBeat message from a node, it calls the postponeParentHandler method for all topics for which that node is its parent. By having this data structure locally, we avoid sending lists of topics for which a node is parent in the HeartBeat message (this would cause the Heartbeat message to grow very large).

m_alreadySentHBNodes

protected java.util.Set m_alreadySentHBNodes
Optimization on number of HeartBeat Messages sent. Each node keeps track of the distinct children to which it has sent a PUBLISH message in last HeartBeat period. Thus in the scheduleHB() method which denotes the end of the previous HeartBeatPeriod, it need not send an explicit HeartBeat message to these 'marked' children, since a PUBLISH message is an implicit keep-alive message from the parent that it is alive.

m_ackOnSubscribeSwitch

public boolean m_ackOnSubscribeSwitch
The AckOnSubscribe switch if true activates the immediate sending of ACK by a node when it receives a SUBSCRIBE message from its child for a topic. Otherwise, this immediate ACK is not sent. This flag is set to TRUE. Setting it to false will cause several more messages in the form of MessageRequestToParent and MessageReplyFromParent to be exchanged between the child node and the parent node, when the child node receives a HeartBeat message from the parent. NOTE that if the HeartBeat message maintained a list of topics for which the child node(receiver of heartbeat message) was its child, then the AckOnSubscribe switch could have been set to false and these extra messages in the form of MessageRequestToParent and MessageReplyFromParent could have been got rid of. But due to scalability issues of sending the list of topics in the HeartBeat message we have adopted the current approach of setting the AckOnSubscribe switch to TRUE and additionally having the MessageRequestToParent and MessageReplyFromParent type of message.

m_address

protected static rice.pastry.messaging.Address m_address
The receiver address for the scribe system.

m_sendOptions

protected rice.pastry.routing.SendOptions m_sendOptions
The SendOptions object to be used for all messaging through Pastry.

m_credentials

protected static rice.pastry.security.Credentials m_credentials
The Credentials object to be used for all messaging through Pastry.

m_securityManager

protected rice.scribe.security.IScribeSecurityManager m_securityManager
Handles all the security verification.

m_maintainer

public rice.scribe.maintenance.ScribeMaintainer m_maintainer
The ScribeMaintainer object handles all the tree maintenance activities like the sending of heartbeat messages and issuing tree repair events for all the topics residing on the local node.

Constructor Detail

Scribe

public Scribe(rice.pastry.PastryNode pn,
              rice.pastry.security.Credentials cred)
Constructor.
Parameters:
pn - the pastry node that client will attach to.
cred - the credentials associated with this scribe object.

Method Detail

setTreeRepairThreshold

public void setTreeRepairThreshold(int value)
The tree repair event for a particular topic in Scribe is triggered when a node misses a certain threshold 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 tree repair threshold.

getTreeRepairThreshold

public int getTreeRepairThreshold()
Gets the tree repair threshold value.
Returns:
the tree repair threshold value

isReady

public boolean isReady()
Returns true is the Scribe substrate is ready. The Scribe substrate is ready when underlying PastryNode is ready.

registerApp

public void registerApp(rice.scribe.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.

notifyReady

public void notifyReady()
This is called when the underlying pastry node is ready. With regard to Scribe, we schedule the periodic tree maintenance activities when the pastry network is a Distributed network instead of a simulate network.

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.

isRoot

public boolean isRoot(rice.pastry.NodeId topicId)
Returns true if the local node is currently the root(the node that is closest to the topicId) of the topic.
Returns:
true if the local node is currently the root for the topic.

create

public boolean create(rice.pastry.NodeId topicId,
                      rice.pastry.security.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
topicID - 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(rice.pastry.NodeId topicId,
                    rice.scribe.IScribeApp subscriber,
                    rice.pastry.security.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
topicID - 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.

leave

public boolean leave(rice.pastry.NodeId topicId,
                     rice.scribe.IScribeApp subscriber,
                     rice.pastry.security.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
topicID - 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(rice.pastry.NodeId topicId,
                         java.lang.Object obj,
                         rice.pastry.security.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
topicID - 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.

generateTopicId

public rice.pastry.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 Topic id.

getAddress

public rice.pastry.messaging.Address getAddress()
Returns the address of this client.
Returns:
the address.

getCredentials

public rice.pastry.security.Credentials getCredentials()
Returns the credentials of this client.
Returns:
the credentials.

messageForAppl

public void messageForAppl(rice.pastry.messaging.Message msg)
Called by pastry when a message arrives for this client.
Parameters:
msg - the message that is arriving.

enrouteMessage

public boolean enrouteMessage(rice.pastry.messaging.Message msg,
                              rice.pastry.NodeId target,
                              rice.pastry.NodeId nextHop,
                              rice.pastry.routing.SendOptions opt)
Called by pastry when a message is enroute and is passing through this node.
Parameters:
msg - the message that is passing through.
target - the final destination node id.
nextHop - the 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(rice.pastry.NodeHandle nh,
                          boolean wasAdded)
Called by pastry when the leaf set changes.
Parameters:
nh - the handle of the node that entered or left the leafset.
wasAdded - true if the node was added, false if it was removed.

getNodeHandle

public rice.pastry.NodeHandle getNodeHandle()
Returns the handle of the local node on which this Scribe application resides.
Returns:
the node handle.

getSendOptions

public rice.pastry.routing.SendOptions getSendOptions()
Returns the send options in the Scribe system.
Returns:
the send options.

getSecurityManager

public rice.scribe.security.IScribeSecurityManager getSecurityManager()
Returns the security manager from the Scribe node.
Returns:
the security manager.

makeSubscribeMessage

public rice.scribe.messaging.ScribeMessage makeSubscribeMessage(rice.pastry.NodeId tid,
                                                                rice.pastry.security.Credentials c)
Makes a subscribe message using the current Pastry node as the source.
Parameters:
tid - the topic id the message refers to.
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeUnsubscribeMessage

public rice.scribe.messaging.ScribeMessage makeUnsubscribeMessage(rice.pastry.NodeId tid,
                                                                  rice.pastry.security.Credentials c)
Makes an unsubscribe message using the current Pastry node as the source.
Parameters:
tid - the topic id the message reffers to.
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeCreateMessage

public rice.scribe.messaging.ScribeMessage makeCreateMessage(rice.pastry.NodeId tid,
                                                             rice.pastry.security.Credentials c)
Makes a create message using the current Pastry node as the source.
Parameters:
tid - the topic id the message reffers to.
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makePublishMessage

public rice.scribe.messaging.ScribeMessage makePublishMessage(rice.pastry.NodeId tid,
                                                              rice.pastry.security.Credentials c)
Makes a publish message using the current Pastry node as the source.
Parameters:
tid - the topic id the message reffers to.
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeHeartBeatMessage

public rice.scribe.messaging.ScribeMessage makeHeartBeatMessage(rice.pastry.security.Credentials c)
Makes a heart-beat message using the current Pastry node as the source.
Parameters:
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeAckOnSubscribeMessage

public rice.scribe.messaging.ScribeMessage makeAckOnSubscribeMessage(rice.pastry.NodeId tid,
                                                                     rice.pastry.security.Credentials c)
Makes a AckOnSubscribe message using the current Pastry node as the source.
Parameters:
tid - the topic id the message reffers to.
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeRequestToParentMessage

public rice.scribe.messaging.ScribeMessage makeRequestToParentMessage(rice.pastry.security.Credentials c)
Makes a RequestToParent message using the current Pastry node as the source.
Parameters:
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeReplyFromParentMessage

public rice.scribe.messaging.ScribeMessage makeReplyFromParentMessage(rice.pastry.security.Credentials c)
Makes a ReplyFromParent message using the current Pastry node as the source.
Parameters:
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

makeScribeMaintenanceMessage

public rice.scribe.messaging.ScribeMessage makeScribeMaintenanceMessage(rice.pastry.security.Credentials c)
Makes a ScribeMaintenance message using the current Pastry node as the source.
Parameters:
c - the credentials that will be associated with the message
Returns:
the ScribeMessage.

getTopic

public rice.scribe.Topic getTopic(rice.pastry.NodeId topicId)
Returns the topic object associated with topicId.
Parameters:
topicId - the topic id
Returns:
the Topic associated with the topicId

getTopics

public java.util.Vector getTopics()
Method to access the list of topics this scribe is responsible for. Returns a vector of topics residing on this node.

getDistinctChildren

public java.util.Vector getDistinctChildren()
Gets the Vector of distinct children of this local node in multicast tree of all topics.
Returns:
Vector of distinct children

addChildForTopic

public void addChildForTopic(rice.pastry.NodeHandle child,
                             rice.pastry.NodeId topicId)
Adds a child for a topic into the distinctChildrenTable. If this child already exists, then we add this topic into its corresponding list of topics for which it is our child. Otherwise, we create a new entry into the hashtable.
Parameters:
child - The NodeHandle of Child
topicId - The topicId for the topic for which we are adding this child

removeChildForTopic

public void removeChildForTopic(rice.pastry.NodeHandle child,
                                rice.pastry.NodeId topicId)
Removes a child for a topic from the distinctChildrenTable. See if we already have it as a child for some other topic , if yes then remove this topicId from the list of topics for which this node is our child. Otherwise, we remove the entry from the hashtable since the list of topics becomes empty.
Parameters:
child - The NodeHandle of Child
topicId - The topicId for the topic for which we are removing this child

getTopicsForChild

public java.util.Vector getTopicsForChild(rice.pastry.NodeHandle child)
Gets the vector of topicIds for which given node is a child.
Parameters:
child - The NodeHandle of child node.
Returns:
Vector of topicIds for which this node is a child.

getDistinctParents

public java.util.Vector getDistinctParents()
Gets the Vector of distinct parent of this local node in the multicast trees of all topics.
Returns:
Vector of distinct parents

removeParentForTopic

public void removeParentForTopic(rice.pastry.NodeHandle parent,
                                 rice.pastry.NodeId topicId)
Removes a parent for a topic fromthe distinctParentTable. See if we already have it as a parent for some other topic , if yes then remove this topicId from the list of topics for which this node is our parent. Otherwise, we remove the entry from the hashtable since the list of topics becomes empty.
Parameters:
parent - The NodeHandle of Parent
topicId - The topicId for the topic for which we are removing this parent

addParentForTopic

public void addParentForTopic(rice.pastry.NodeHandle parent,
                              rice.pastry.NodeId topicId)
Adds a parent for a topic into the distinctParentTable. If this child already exists, then we add this topic into its corresponding list of topics for which it is our parent. Otherwise, we create a new entry into the hashtable.
Parameters:
child - The NodeHandle of Parent
topicId - The topicId for the topic for which we are adding this parent

getTopicsForParent

public java.util.Vector getTopicsForParent(rice.pastry.NodeHandle parent)
Gets the vector of topicIds for which given node is our parent.
Parameters:
parent - The NodeHandle of parent node.
Returns:
Vector of topicIds for which this node is our parent.

addChildToAlreadySentHBNodes

public boolean addChildToAlreadySentHBNodes(rice.pastry.NodeId childId)
Adds a child to the list of nodes to which this node has already send a implicit HeartBeat message in the form of Publish message in this Heartbeat period.
Parameters:
childId - NodeId of child.
Returns:
true if child already exists else false

getAlreadySentHBNodes

public java.util.Vector getAlreadySentHBNodes()
Gets the vector of nodes to which an implicit HeartBeat in form of Publish message was sent in last HeartBeat period.
Returns:
Vector of child nodes to which a publish message was sent in last HeartBeat period.

clearAlreadySentHBNodes

public void clearAlreadySentHBNodes()
The set is cleared so that the set contains only those nodes to which Publish message was sent in last HeartBeat period.

getParent

public rice.pastry.NodeHandle getParent(rice.pastry.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.

getChildren

public java.util.Vector getChildren(rice.pastry.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.