[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/07 07:25:43

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

Log message:
        more API, write ups

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/storm/storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst.diff?tr1=1.10&tr2=1.11&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.10 
storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst:1.11
--- storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst:1.10        Mon Jul 
 7 06:44:48 2003
+++ storm/doc/pegboard/storm_with_tapestry--hemppah/peg.rst     Mon Jul  7 
07:25:43 2003
@@ -5,8 +5,8 @@
 
 :Authors:  Hermanni Hyytiälä
 :Date-Created: 2003-07-03
-:Last-Modified: $Date: 2003/07/07 10:44:48 $
-:Revision: $Revision: 1.10 $
+:Last-Modified: $Date: 2003/07/07 11:25:43 $
+:Revision: $Revision: 1.11 $
 :Status:   Incomplete
 
 .. :Stakeholders:
@@ -15,18 +15,13 @@
 
 .. Affect-PEGs:
 
-- this document describes the usage of Tapestry with Storm
-- possibly some architectural changes are required to Storm if Tapestry is
-  taken to in use. Thus, this document is needed
-- first, this PEG discusses general aspects of Tapestry, it's API and the 
-  usage of the API with other applications
-- introduction to Tapestry, the SEDA model, Tapestry API, how to use Tapestry 
-  with other application  
-- then, a proposal of usage with Storm
-- pseudo code: search and insert operations
-- simple "implementation" and architectural design
-- possible changes are listed
-- this document is based on Tapestry release 2.0
+This document describes the use of Tapestry overlay with Storm. We start by 
+proviving a short introduction to Tapestry, to the SEDA model and to the 
Tapestry 
+API. Then, we propose new classes and a pseudo code to be included into Storm 
+code base. Pseudo code describes a simple StormTapestryManager which supports
+query and insert operations in a Tapestry overlay.
+
+This document is based on Tapestry 2.0 release.
 
 Issues
 ======
@@ -37,43 +32,43 @@
 Introduction to Tapestry
 ========================
 
-- currently Tapestry_ implements the DOLR abstracion
-- other abstraction can be implemented also (e.g., DHT)
-- two primary functions: 1) efficient way for nodes to communicate across 
-  an overlay and 2) effcient object location
-- objects are *published* with object to location mappings (pointers)
-- differs from DHTs in that always use the closest available object
-- routing table consists of levels of neighbor links 
-- each level represents a matching prefix up to a digit position in the ID
-- for each level, neighbor links are selected based on "closest" in network 
-  latency
-- along the publication process, the overlay deposits a pointer at every hop
-  along the way
-- when an object is searched, a query is forwarded towards object's 
-  publication route, and when a query run into a first pointer, overlay
-  directly forwards to the object  
-- written in Java (currently JDK 1.3)
-- uses SEDA (Staged Event-Driven Architecture) framwork
-- approximately 57000 lines of code
-- shares codebase with Oceanstore
+Tapestry_ is a application level Peer-to-Peer overlay. Currently Tapestry_ 
+supports the DOLR abstracion but other abstraction can be implemented 
+(e.g., DHT). Tapestry's DOLR interface has two primary functions: efficient 
+way for nodes to communicate across the overlay and effcient object location. 
+In Tapestry, objects are *published* with object to location mappings (a.k.a. 
+pointers). This operation differs from DHTs in that always use the closest 
+available object.
+
+Tapestry's routing table consists of levels of neighbor links. Each level 
+represents a matching prefix up to a digit position in the ID. Additionally
+for each level, neighbor links are selected based on closest in network 
+*latency*. Along the publication process, the overlay deposits a pointer at 
+every hop along the way. When an object is searched, a query is forwarded 
+towards object's publication route, and when a query run into a first pointer, 
+overlay directly forwards to the object.
+
+Tapestry 2.0 release is written in Java and uses SEDA (Staged Event-Driven 
+Architecture) framwork for thread and I/O-operations. Tapestry's code base
+has approximately 57000 lines of code and shares some code with Oceanstore's
+code base.
 
 Overview of SEDA
 ================
 
-- asynchronous I/O library (similar to JDK 1.4's java.nio package)
-- stages communicate with each other by sending events
-- each Tapestry component is implemented as a stage
-- stage runs as a thread which starts by executing initialization routines 
-  and then enters an event loop
-- inside each JVM, a dispatcher monitors all messages and events, 
-  and delivers copies to each stage that subscribes to messages of that type
-- a (common) Tapestry node uses StaticTClient stage, DynamicTClient stage, 
-  Router stage and Tapestry application stage
-- for each stage, a config file is required to specify stage's properties
-  (XML-like tag structure)
-- during the initialization phase, a stage specifies which event and messages 
-  it wants to "listen" to
-- for Storm, the Tapestry application stage is the most important 
+SEDA is a asynchronous I/O library (similar to JDK 1.4's java.nio package). In
+SEDA there are stages and they communicate with each other by sending events.
+A stage runs as a thread which starts by executing initialization routines and 
+then enters an event loop.  Inside each JVM, a dispatcher monitors all 
messages 
+and events, and delivers copies to each stage that subscribes to messages of 
+that type.
+
+Each Tapestry component is implemented as a stage. A (common) Tapestry node 
+uses StaticTClient stage, DynamicTClient stage, Router stage and Tapestry 
+application stage. For each stage, a config file is required to specify 
+stage's properties (XML-like tag structure). During the initialization phase, 
+a stage specifies which event and messages it wants to "listen" to. For Storm, 
+the Tapestry application stage is the most important. 
 
 
 Overview of Tapestry API
@@ -100,19 +95,19 @@
 Using Tapestry API from other applications
 ==========================================
 
-- confgig file for defining a Storm stage (Tapestry application stage)
-
 According to the `Tapestry programmer's guide`_, there three steps to write
 a Tapestry application:
 
    - Write the necessary messages to interface with Tapestry
-   - Write an Eventhandler class that would serve as the application
+   - Write an event handler class that would serve as the application
    - Write configuration file(s) to define stages and specify initialization 
      arguments
      
-Interface with Tapestry
+Custom messages for Tapestry
 -----------------------
 
+Again, According to the `Tapestry programmer's guide`_:
+
 1. An application must extend extending the abstract API message types, e.g.:
 
    public class StormMsg extends TapestryPublishmsg {
@@ -125,32 +120,30 @@
    
 3. Do not write a working type_code method
 
-4. Register your message class 
-
-Eventhandler class
+ 
+An event handler class
 ------------------
 
-1. Write a class which extends SEDA's existing stages, e.g.,
+1. Write a eventhandler class which extends SEDA's existing stages, e.g.,
 
-  public class StormP2p extends StandardStage
+  public class StormTapestryManager implements EventHandlerIF
   
-2. In Eventhandler class, implement a hanleEvent method which will
+2. In a eventhandler class, implement a hanleEvent method which will
    process registered messages
    
-3. In Eventhandler class, implement a init method which will define
-   the messages that are "listened" for this class
+3. In a 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
 
 Using Tapestry with Storm
 =========================
 
-- in this section, we will outline the design which would allow Storm to
-  Tapestry's routing services
-  
-  
-  
-- For finding Storm blocks in a Tapestry overlay, we must create:
+In this section, we will outline the design which would allow Storm to
+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:
@@ -181,20 +174,22 @@
      implements ostore.util.QuickSerializable) to carry a requested Storm
      block being sent to a original requester
    
-- For interacting Storm's storage model with Tapestry:
+For interacting Storm's storage model with Tapestry we must create and event
+handler class:
 
-   - StormTapestryManager class which
-     - registers Storm to handle Storm-related Tapestry events and messages
-     - handles and dispatches Storm-related Tapestry events and messages
-     - interacts with a local Storm pool
+   - StormTapestryManager class (implements sandStorm.api.EventHandlerIF) for 
+     listening standard Tapestry events, registering custom Storm messages, 
+     dispatching custom Storm messages and interacting with a local Storm pool
      
      
- PSEUDOCODE for Storm
+Here, we propose a simple StormTapestryManager pseudo code. This is an event
+handler class for Tapestry. In addition, this class provides Storm block
+query and insert operations in a Tapestry overlay.
 
        class StormTapestryManager implements EventHandlerIF {
        
                // dispatcher which dispatch all items
-               // to target peer
+               // to target peer (Mandatory: sandStorm requires this)
                method dispatch (QueueElementIF item) {
                        //try do dispatch an item
                        try {
@@ -207,6 +202,7 @@
                // general initialization method
                // that handles subscribes this stage
                // to listen certain events and messages
+               // (Mandatory: sandStorm requires this)
                method init (ConfigDataIF config) {
  
                // find our NodeId 
@@ -222,7 +218,7 @@
                // create peer ID based on peer's public key
                 _peer = new SHA1Hash (pkey);
                 
-                // the *events* which we want to listen
+                // the mandatory *events* which we want to listen
 
                 array event_types = {
                 "seda.sandStorm.api.StagesInitializedSignal",
@@ -234,7 +230,7 @@
                        classifier.subscribe (event_type[i])
                 }
                
-               // the *messages* we want receive through Tapestry
+               // the mandatory *messages* we want receive through Tapestry
 
                array message_types = {
                "org.nongnu.storm.p2p.tapestry.StormErrorMsg",
@@ -263,6 +259,7 @@
                }
                
                // handles *all* events which stage is listening
+               // (Mandatory: sandStorm requires this)
                 method handleEvents(QueueElementIF array items) 
                 throws EventHandlerException {
                 
@@ -272,6 +269,7 @@
                
                // handles single event for this stage. handleEvents
                // method gives an item this method
+               // (Mandatory: sandStorm requires this)
                method handleEvent(QueueElementIF item) {
                
                if (item instanceof StagesInitializedSignal) {
@@ -313,6 +311,11 @@
                        dispatch(response)              
                }
                
+               // 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
                method createQuery(){
@@ -344,6 +347,23 @@
                                dispatch(unpublishMsg)
                }
                
+               // dispatch TapestryPublishMsg for a single block in the 
+               // local Storm pool             
+               method publishSingleStormBlock(blockGUID) {
+                       tag = new BlockIDTag(blockGUID)                         
+                       publishMsg = new 
+                       TapestryPublishMsg(blockGUID, tag)
+                       dispatch(publishMsg)
+               }
+               
+               // dispatch TapestryUnpublishMsg for a single block in the 
+               // local Storm pool             
+               method unpublishSingleStormBlock(blockGUID) {
+                       tag = new BlockIDTag(blockGUID)                         
+                       unpublishMsg = new 
+                       TapestryUnpublishMsg(blockGUID, tag)
+                       dispatch(unpublishMsg)
+               }
        }
     
 .. more to come