[Gzz-commits] storm/doc/pegboard/storm_with_tapestry--hemppah...

[Hermanni Hyytiälä]

CVSROOT:        /cvsroot/storm
Module name:    storm
Branch:         
Changes by:     Hermanni Hyytiälä <address@hidden>      03/07/08 05:17:37

Modified files:
        doc/pegboard/storm_with_tapestry--hemppah: peg.rst 

Log message:
        more language

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/storm/storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst.diff?tr1=1.17&tr2=1.18&r1=text&r2=text

Patches:
Index: storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst
diff -u storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst:1.17 
storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst:1.18
--- storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst:1.17        Tue Jul 
 8 04:24:38 2003
+++ storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst     Tue Jul  8 
05:17:36 2003
@@ -5,8 +5,8 @@
 
 :Authors:  Hermanni Hyytiälä
 :Date-Created: 2003-07-03
-:Last-Modified: $Date: 2003/07/08 08:24:38 $
-:Revision: $Revision: 1.17 $
+:Last-Modified: $Date: 2003/07/08 09:17:36 $
+:Revision: $Revision: 1.18 $
 :Status:   Incomplete
 
 .. :Stakeholders:
@@ -157,14 +157,14 @@
 An event handler class
 ------------------
 
-1. Write an eventhandler class which extends SEDA's existing stages, e.g.,
+1. Write an event handler class which extends SEDA's existing stages, e.g.,
 
   public class StormTapestryManager implements EventHandlerIF
   
-2. In a eventhandler class, implement a hanleEvent method which will
+2. In an event handler class, implement a hanleEvent method which will
    process registered messages
    
-3. In a eventhandler class, implement a init method which will define
+3. In an eventhandler class, implement a init method which will define
    the events and messages that are "listened" for this class
 
 4. Register your custom message classes
@@ -172,20 +172,20 @@
 Using Tapestry with Storm
 =========================
 
-In this section, we will outline the design which would allow Storm to
+In this section, we will outline a design which would allow Storm to use
 Tapestry's routing services.
 
 For finding Storm blocks in a Tapestry overlay, we must create custom message
 classes:
 
-   - BlockIDTag class for Storm blocks' IDs (implements 
-     ostore.tapestry.api.TapestryTag) for storing query specific information:
+   - BlockIDTag class (implements ostore.tapestry.api.TapestryTag) for 
+     Storm blocks' IDs for storing query specific information:
      in our case, we store at least block's GUID and other related info 
      (if needed)
 
-   - BlockIDQuery (implements ostore.tapestry.api.TapestryQuery) to receive an 
-     object identified by a BlockIDTag, dispatch a 
-     ostore.tapestry.api.TapestryLocateMsg that contains a BlockIDQuery  
+   - BlockIDQuery class (implements ostore.tapestry.api.TapestryQuery) to 
receive an 
+     object identified by a BlockIDTag (and dispatch a 
+     ostore.tapestry.api.TapestryLocateMsg that contains a BlockIDQuery)  
      
    - StormLocateMsg class (extends ostore.tapestry.api.TapestryLocateMsg, 
      implements ostore.util.QuickSerializable) for locating Storm blocks 
@@ -194,20 +194,20 @@
    - StormResponseMsg class (extends ostore.tapestry.api.TapestryRouteMsg,
      implements ostore.util.QuickSerializable) to carry meta data for a 
      requested Storm block. This is an optional class, i.e., if we want
-     to see query results, we may use this
+     to see query results, we could use this class
      
-   - StormBlockRequestMsg (extends ostore.tapestry.api.TapestryRouteMsg,
+   - StormBlockRequestMsg class (extends ostore.tapestry.api.TapestryRouteMsg,
      implements ostore.util.QuickSerializable) to request a specific Storm
      block
    
-   - StormErrorMsg (extends ostore.tapestry.api.TapestryRouteMsg,
+   - StormErrorMsg class (extends ostore.tapestry.api.TapestryRouteMsg,
      implements ostore.util.QuickSerializable) for sending error messages
    
    - StormBlockMsg class (extends ostore.tapestry.api.TapestryRouteMsg,
      implements ostore.util.QuickSerializable) to carry a requested Storm
      block being sent to a original requester
    
-For interacting Storm's storage model with Tapestry we must create and event
+For interacting Storm's storage model with Tapestry we must create an event
 handler class:
 
    - StormTapestryManager class (implements sandStorm.api.EventHandlerIF) for 
@@ -216,13 +216,15 @@
      
      
 Here, we propose a simple StormTapestryManager pseudo code. This is an event
-handler class for Tapestry services. In addition, this class provides Storm
-block query and insert operations in a Tapestry overlay.
+handler class for Tapestry services. In addition to basic event handling 
+functionality, this class supports Storm block query and insert operations 
+in a Tapestry overlay.
 
        class StormTapestryManager implements EventHandlerIF {
        
-               // dispatcher which dispatch all items
-               // to target peer (Mandatory: sandStorm requires this)
+               // Dispatcher which dispatches all items
+               // to a target peer. 
+               // (Mandatory: sandStorm requires this)
                method dispatch (QueueElementIF item) {
                        //try do dispatch an item
                        try {
@@ -232,26 +234,27 @@
                        }
                }
 
-               // general initialization method
+               // General initialization method
                // that handles subscribes this stage
-               // to listen certain events and messages
+               // to listen certain events and messages.
                // (Mandatory: sandStorm requires this)
                method init (ConfigDataIF config) {
  
                // find our NodeId 
                self_node_id = new NodeId 
                
-               // initialize the appropriate
+               // Initialize the appropriate
                // instance of the Classifier. The Classifier handles the 
                // publish/subscribe mechanism used for
                // event dispatch between stages.
                
                classifier = Classifier.getClassifier(self_node_id = new NodeId)
                
-               // create peer ID based on peer's public key
-                _peer = new SHA1Hash (pkey);
+               // Create peer ID based on peer's public key.
+                peer = new SHA1Hash (publicKey);
                 
-                // the mandatory *events* which we want to listen
+                // The *events* which we want to listen.
+                // (Mandatory: sandStorm requires this)
 
                 array event_types = {
                 "seda.sandStorm.api.StagesInitializedSignal",
@@ -263,7 +266,8 @@
                        classifier.subscribe (event_type[i])
                 }
                
-               // the mandatory *messages* we want receive through Tapestry
+               // The *messages* we want receive through Tapestry.
+               // (Mandatory: sandStorm requires this)
 
                array message_types = {
                "org.nongnu.storm.p2p.tapestry.StormErrorMsg",
@@ -277,13 +281,13 @@
                for (From i=0 To numberOf(message_types)) {
            
                   // First, register messages we intend to
-                  // receive
+                  // receive.
                   
                   TypeTable.register_type(messages_types[i])
                   
-                  // Second, we require that inbound field is
+                  // Second, require that inbound field is
                   // set to true.  Otherwise, we will see the messages that we
-                  // send as well 
+                  // send as well. 
 
                   classifier.subscribe (message_type[i], verifyInbound);
                }
@@ -291,7 +295,7 @@
                 
                }
                
-               // handles *all* events which stage is listening
+               // Handles *all* events which stage is listening.
                // (Mandatory: sandStorm requires this)
                 method handleEvents(QueueElementIF array items) 
                 throws EventHandlerException {
@@ -300,8 +304,8 @@
                        handleEvent(items[i])                   
                 }
                
-               // handles single event for this stage. handleEvents
-               // method gives an item this method
+               // Handles single event for this stage. handleEvents
+               // method gives an item to this method as a parameter.
                // (Mandatory: sandStorm requires this)
                method handleEvent(QueueElementIF item) {
                
@@ -309,48 +313,48 @@
                        // StagesInitializedSignal received
            
                } else if (item instanceof TapestryReadyMsg) {
-                       // connected        
+                       // Connected to network.            
                        publishLocalStormPool()
                } else if (item instanceof TapestryDetachConfirm) {
-                       // disconnected
+                       // Disconnected from network.
                        unpublishLocalStormPool()
                } else if (item instanceof TapestryLocateFailure) {
-                       // Search failed
-                       
+                       // Search failed.                       
                } else if (item instanceof StormLocateMsg) {
+                       // Handle StormLocateMsg with a custom method.
                        handleStormLocateMsg(item)
-
                } else if (item instanceof StormResponseMsg) {
-                       handleStormResponseMsg(item)
-                       
+                       // Handle StormResponseMsg with a custom method.
+                       handleStormResponseMsg(item)                    
                } else if ( item instanceof XXX ) {
+                       // Handle message XXX with a custom method.
                        handleOtherMsg(item)
                        ...
-               } else {
+               } else {                        
                        //  Unknown QueueElementIF item
                }               
                                
                }
                
-               // handles a certain type of event(StormLocateMsg)
+               // Handles a certain type of event (StormLocateMsg).
                method handleStormLocateMsg(item){
                        results = performLocalSearch()
                        dispatch(results)               
                }
                
-               // handles a certain type of event(StormResponseMsg)
+               // Handles a certain type of event (StormResponseMsg).
                method handleStormResponseMsg(item){
                        response = createResponse()
                        dispatch(response)              
                }
                
-               // handles a certain type of event(XXX)
+               // Handles a certain type of event (XXX).
                method handleXXXMsg(item){
                        // do something 
                }
                        
-               // create a Storm query to a Tapestry network
-               // Query tag is Storm block's GUID
+               // Create a Storm query to a Tapestry network,
+               // Query tag is Storm block's GUID.
                method createQuery(){
                        blockTag = new BlockIDTag(blockGUID)
                        q = new StormQuery()
@@ -358,8 +362,8 @@
                        dispatch(queryMsg)
                }
                
-               // dispatch TapestryPublishMsg for all blocks in the 
-               // local Storm pool
+               // Dispatch TapestryPublishMsg for all blocks in a 
+               // local Storm pool.
                method publishLocalStormPool(){         
                        for each block in localPool
                                block = localPool.getBlock()
@@ -369,8 +373,8 @@
                                dispatch(publishMsg)            
                }
                
-               // dispatch TapestryUnpublishMsg for all blocks in the 
-               // local Storm pool
+               // Dispatch TapestryUnpublishMsg for all blocks in a 
+               // local Storm pool.
                method unpublishLocalStormPool(){               
                        for each block in localPool
                                block = localPool.getBlock()
@@ -380,8 +384,8 @@
                                dispatch(unpublishMsg)
                }
                
-               // dispatch TapestryPublishMsg for a single block in the 
-               // local Storm pool             
+               // Dispatch TapestryPublishMsg for a single block in a 
+               // local Storm pool.            
                method publishSingleStormBlock(blockGUID) {
                        tag = new BlockIDTag(blockGUID)                         
                        publishMsg = new 
@@ -389,8 +393,8 @@
                        dispatch(publishMsg)
                }
                
-               // dispatch TapestryUnpublishMsg for a single block in the 
-               // local Storm pool             
+               // Dispatch TapestryUnpublishMsg for a single block in a 
+               // local Storm pool.            
                method unpublishSingleStormBlock(blockGUID) {
                        tag = new BlockIDTag(blockGUID)                         
                        unpublishMsg = new 
@@ -399,12 +403,12 @@
                }
        }
     
-.. more to come
 
 Changes
 =======
 
-.. there will be some changes
+Eight new classes will be implemented under org.nongnu.storm.p2p.tapestry 
package 
+into the Storm code base, if this PEG document is accepted.  
 
 .. _`Tapestry programmer's guide`: 
http://www.cs.berkeley.edu/%7Eravenben/tapestry/html/guide.html
 .. _Tapestry: 
http://www.cs.berkeley.edu/~ravenben/publications/pdf/tapestry_jsac.pdf