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