The OceanStore Project OceanStore HelloWorld HOWTO by Hakim Weatherspoon, Chiu Wah Kelvin So, and Jason Lee

Background and Motivation

The goal of this OceanStore HelloWorld excercise is for each user to individually practice writing, compiling, running, and debuging your own OceanStore code. Please attempt to work through the excercise before looking at answer solution. Also, you can direct questions to Hakim Weatherspoon <hweather@cs.berkeley.edu>, Jason Lee <jlee81@cs.berkeley.edu>, Jeremy Stribling <strib@cs.berkeley.edu>, and/or Chiu Wah Kelvin So <kelvinso@cs.berkeley.edu>.

Your mission, should you accept it, is to create two nodes that pass a simple msg to each: client->server "Hello! How are you?", server->client "Great! The weather is wonderful today!"

Directions:

Note all DD java classes you will be using are defined in the dd.api package. Also, all HelloWorld classes and files will be placed into the dd.demo.helloworld.step1 package/directory.

Note make sure to be explicit about what classes are being imported (e.g. do NOT use import ostore.util.*), make sure to comment code (look at dd.directmail.impl.DirectMailTester for an example), and make sure to break up code into constants, static variables, variables, static constructors, constructors, static methods, methods, and inner classes (again DirectMailTester and other classes mentioned as examples are good examples).

• Protocol:
  
  • HelloWorldServer publishes the fact that it is a helloworld server.
    
    • Use a DDPublishReq to publish a service in DD.
    • A DDPublishReq takes as input a GUID (Globally Unique IDentifier) for the service and a DDTag.
    • To create a GUID for the helloworld service provider use ostore.util.SHA1Hash to hash "HelloWorld Service Provider".
    • To create a DDTag, extend the java class with a service that exhibits the service name (i.e. HelloWorldTag extends DDTag)
  • HelloWorldClient locates and sends msg to HelloWorldServer by sending a HelloWorldLocateMsg.
    • You locate and send a msg to a service by extending the DDLocateMsg java class. (i.e. HelloWorldLocateMsg extends DDLocateMsg)
    • The HelloWorldLocateMsg constructor takes as input a Service Provider GUID, a DDQuery, a DDQueryState, and a Unique ID to identify any response to the msg (e.g. msg response or a DDLocateFailure).
    • To create a GUID for the helloworld service provider use ostore.util.SHA1Hash to hash "HelloWorld Service Provider".
    • Create HelloWorldQuery that extend DDQuery. HelloWorldQuery returns DDQueryResultMatch if a HelloWorldTag is found; otherwise, returns a DDQueryResultNoMatch.
    • You will not need a DDQueryState since you only need to find one helloworld service provider.
    • The unique id can be a hash of a unique string. For example, use a instance variable that monotonically increases and hash that number with the stage name and/or time.
  • When the HelloWorldServer receives the HelloWorldLocateMsg it needs to print the msg to the screen and respond with a HelloWorldRouteMsg acknowledging that it received the msg and containing a response msg that the client can print to the screen.
  • When the client receives the response it needs to print the msg to the screen.
  • After printing the msg, the client can exit.
  • Since msg's can be dropped the client needs to timeout and resend HelloWorldLocateMsg's. The ostore.dispatch.Resender will assist in timingout as explained below.
• Examples - Good examples to look at are:
  
  • Standard Stage: Use ostore.archive.ArchiverStage or ostore.introspect.SDMBuilder as a reference
    HINT: Make sure you read Standard Stage thoroughly; note the predefined stuff. Also, look at the ArchiverStage at how they use Signal with resender.
  • DDPublishReq: ostore.archive.ArchiverStage or ostore.archive.ArchivalStorageStage (search for 'new DDPublishMsg')
  • DDPublishResp: demo.dynamic.Test
  • DDTag: ostore.archive.FragmentTag or ostore.inner.InnerRingTag
  • DDLocateMsg: ostore.archive.RequestFragMsg or ostore.inner.UpdateReqMsg
  • DDQuery: ostore.archive.RequestFragQuery or ostore.inner.InnerRingQuery
  • DDQueryState: ostore.archive.RequestFragQueryState.
  • DDRouteMsg: ostore.archive.RequestFragRespMsg or ostore.dtree.DownDTreeMsg
• create a helloworld step1 impl directory in dd/demo/helloworld/step1/impl (i.e. oceanstore/dd/demo/helloworld/step1/impl), and a helloworld step1 api directory in dd/demo/helloworld/step1/api
  
  • HelloWorldServer and HelloWorldClient you create will be placed in helloworld/step1/impl directory.
  • Make HelloWorldServer and HelloWorldClient part of the demo.helloworld.step1.impl package.
  • HelloWorldLocateMsg, HelloWorldQuery, HelloWorldTag, and HelloWorldRouteMsg you create will be placed in helloworld/step1/api directory.
  and make them part of the demo.helloworld.step1.api package.
• Copy the Makefile file from demo/dynamic into your helloworld/api and helloworld/step1 directory and change the DD_Home path so that it points to root directory of dd.
• Copy the .cvsignore file from ostore/apps/test into your helloworld
• You will have to create two "stages": HelloWorldClient and HelloWorldServer.
  
  • both stages need to extend the ostore.util.StandardStage class and implement the seda.sandStorm.api.SingleThreadedEventHandlerIF
• The HelloWorldServer needs to listen for two events: DDReadyMsg and HelloWorldLocateMsg.
  
  • DDReadyMsg is defined in dd.api package.
  • HelloWorldLocateMsg is a msg you create for the client to locate and send msg to server.
  • In the HelloWorldServer constructor you need to enable your stage to be able to receive events by assigning event_types, inb_msg_types and serializable_types like below
    
// Events to register
event_types = new Class[]{dd.api.DDReadyMsg.class};

// Inbound messages to register (off the wire)
inb_msg_types = new Class[]{demo.helloworld.api.HelloWorldLocateMsg.class};

// Objects that are serializable but not an event or message.
serializable_types = new Class[]{
demo.helloworld.api.HelloWorldQuery.class,
demo.helloworld.api.HelloWorldRouteMsg.class,
demo.helloworld.api.HelloWorldTag.class
};

• The HelloWorldClient needs to listen for four events:
  DDReadyMsg, Signal.AlarmSignal, HelloWorldRouteMsg, DDLocateFailure.
  
  • DDReadyMsg is defined in dd.api package.
  • Signal.AlarmSignal is defined in ostore.dispatch package. Since msg's can get lost you need to timeout and resend them. ostore.dispatch.Resender helps with this. As a consequence, Resender needs your stage to listen for timeouts. ostore.archive.RequestorStage is a good example of how to use the Resender.
  • HelloWorldRouteMsg is a msg you create for the server to respond to the client with.
• The DDReadyMsg contains the node's id (node_guid).
  
  • HelloWorldServer publishes its services AFTER receiving the DDReadyMsg.
  • HelloWorldClient attempts to locate HelloWorldServer AFTER receiving the DDReadyMsg (note: Although HelloWorldClient receives DDReadyMsg, Bamboo is not actually ready for all the stages. Therefore, if HelloWorldClient sends out HelloWorldLocateMsg right after DDReadyMsg, HelloWorldClient will get a DDLocateFailure. To avoid that, HelloWorldClient can use Classifier.dispatch_later to dispatch an event that tells the HelloWorldClient to start a few seconds later after getting DDReadyMsg)
  • The easiest way to create a handler method for each event that can be received. That is, handleDDReadyMsg will send DDPublishMsg for server and/or dispatch_later(StartTest) for client. You can create StartTest by creating an inner class in HelloWorldClient. Also, in Client, create a method to handle StartTest. When receiving StartTest, use resender.resend(HelloWorldLocateMsg).
• The HelloWorldClient needs to record that fact that it sent a HelloWorldLocateMsg and is waiting for a response.
  
  • There is an instance variable resenderin Standard Stage, a Resender object to timeout and resend automatically by resender.resend.
  • There is a table (java.util.HashMap's): resender_tokens in the Standard Stage (records resender tokens to use to cancel resending; that is, resender.cancel(token)).
    
    • The key is the Unique ID described above
    • The element is the resender token.
    • Look at ostore.archive.RequestorStage for example use.
  • When HelloWorldClient receives Signal.AlarmSignal event, HelloWorldClient should handle Signal.AlarmSignal by
resender.process_queues();
resender.clear(false);
    For more details, look at Resender and also the examples mentioned.
• When the HelloWorldServer receives the HelloWorldLocateMsg it will print the msg and respond.
  
  • Use logger.info*message*/) to print out the msg. logger has be instantiated in Standard Stage.
  • Use logger.warn(/*message*/) for warning, and use logger.debug((/*message*/) for debug message. If there is error, use BUG(/*message*/)
  • The response should contain a different msg and the original requests unique id (req.identifier).
  • The req.peer field contains the node guid of the HelloWorldClient. You will need this to send in the HelloWorldRouteMsg to respond to the correct node.
• When the HelloWorldClient receives the HelloWorldRouteMsg it should
  
  • use the unique id to remove the resender token from the _resender_token table,
  • use the token to cancel the resender (resender.cancel( token )),
  • print msg to the screen, and
  • exit.