Building applications using the XML Store

The XML Store is a peer-to-peer system designed to run across a large number of machines. For test purposes you can set up more servers on one machine, but they need to run on separate virtual machines.

Except when starting the first server, you need to locate one of the other servers in the system, so the new server can enter the peer-to-peer network (this proces is known as "joining" the system). You can either specify the ip-adress (host and port) of a running server or tell the XML Store to look for other servers using a multicast. The latter is practical in a LAN setting.

The name service is a simple server application that associates human readable names with data in the XML Store. Only one name service should be started at a time. Locating the name service can so far only be done by using multicast.

Command Line Options

To start an XML Store Server (a peer in the system), open a shell/DOS prompt and type:

     java XmlStore.jar XmlStoreHome port=NUMBER protocol='tcp'/'udp'bootstrap='multicast'/HOST:PORT disk='multi'/'raf'

To start an XML Store at port 8899 using udp, raf disk and multicast simply write:

     java XmlStore.jar XmlStoreHome port=8899 protocol=udp bootstrap=multicast disk=raf

To start name service, open a shell/DOS prompt and type:

     java XmlStore.jar DirectoryImpl port=NUMBER

Creating and manipulating XML documents

The client can create and manipulate XML documents by using the classes in the package edu.it.xmlstore.xml. Consider a client wishing to produce the following XML fragment, representing a famous line from a play by Shakespeare:

<SPEECH>
  <SPEAKER>
     KING RICHARD III
  </SPEAKER>
  <SPEECH>
     A horse! a horse! my kingdom for a horse!
  </SPEECH>
</SPEECH>

The above could be constructed in the following way:

Node speaker = Element.createElement("SPEAKER",
               new Node[] {CharData.createCharData("KING RICHARD III")});
Node line    = Element.createElement("LINE",
               new Node[] {CharData.createCharData("A horse! a horse! my kingdom for a horse!")});
Node speech =  Element.createElement("SPEECH", 
               new Node[]{newSpeaker, newLine});

If the above XML fragment was stored in a regular text file called ``doc.xml'', the document could be constructed using a method that parses the file to Node representation:

Node speech = Element.createElementFromFile("doc.xml");

Storing and retrieval of documents

To store the document in the peer-to-peer network we need to start an XML Store server. For a client or an upper application layer the XML Store server is accessible through the interface XmlStoreServer, which defines methods such as save(), load(), join() and leave(). XmlStoreHome defines helper methods for initialising an XML Store server. Clients wishing to join the XML Store network simply call XmlStoreHome.createAndJoin() to have an XmlStoreServer instantiated and joined the peer-to-peer network. The document can then be saved. The following shows the above document being saved. Note that port can be any unused port in the system.

int port = 6001;
XmlStoreServer server = XmlStoreHome.createAndJoin(port);
ValueReference ref = server.save(speech);

To load the document, use the ValueReference ref:

Node speech = server.load(ref);

The client can associate the value reference with a human-readable name using the Directory. This makes the value reference available for later retrieval and makes the document available to other interested parties. The following code fragment binds the above document (actually the document's value reference) to a name.

String name = "Quote of the day";
Directory directory = XmlStoreHome.getDirectory(port);      
directory.bind(ref, name);

For a more extensive example of how to build applications using the XML Store, see the email application in package edu.it.xmlstore.mail.