PsEPR Documentation: jClient Guide

The Java package org.psepr.jClient provides and interface to the PsEPR event system. This document describes how to use the extend the jClient package. Javadoc interface documentation is also available.

This library presents a set of objects for the pieces of the PsEPR protocol : classes for a connection, lease, event, payload, etc.

First a connection is made to the PsEPR system. This requires an authenticated service ID so one creates a PsEPRServiceIdentity object. This is passed to PsEPRConnection. In most cases, only one connection is needed for an application as multiple leases can use one connection.

Sending events is done by creating an event, adding the payload to the event and then sending it. A code sample for sending an "attribute" event looks like:

// create and populate the attribute payload
PayloadAttribute myPA = new PayloadAttribute();
myPA.setAttributeName("projectName");
myPS.setAttributeValue("Cute Service");

// create the event
PsEPREvent myEV = new PsEPREvent();
myEV.setDistribution(PsEPREvent.distributionOne);
myEV.toChannel("/example.com/services/cuteservice/status/");
myEV.toService(myService);    // optional
myEV.toInstance(myInstance);  // optional
myEV.setPayload(myPA);
myPConn.sendEvent(myEV);
        

To receive events, a lease on a channel must be aquired. This is done by specifying the type of the event to receive and the routine to receive the event.

Here is a generic code sample to create a lease:

import org.psepr.jClient.*;
...
PsEPRServiceIdentity myID = new PsEPRServiceIdentity("service", "password");
PsERPConnection pConn = new PsEPRConnection(myID);
...
PayloadParser myPP = new myClassImplementingPayloadParser();
EventReceiver myPR = new myClassImplementingEventReceiver();
myPLease = myPCon.getLease(channelName, myPP, myQM);
...
myPConn.releaseLease(myPLease);
        

When starting to use PsEPR, one of the first problems is connecting to the servers. The current list of servers is specified in the configuration file and the most current version can be fetched from http://psepr.org/PsEPRServer/jClient.xml . There is usually a delay while an application is searching for a server. You can watch this searching process (helpful while debugging) by turning on the debug flags in the configuration file. Add the following section to your user configuration file:

<jClient>
  <debug>
    <filterLevel>
      0x0062
    </filterLevel>
  </debug>
</jClient>          
        

Any client sending events on PsEPR has a service ID that is authenticated with the PsEPR infrastructure. For the moment, you must contact the PsEPR maintainer (Robert dot Adams at intel dot com) to get an ID.

The service ID authenticates the service. The service ID is in the from/service element in any received event. There can be many instances of a service and all of these should authenticate as the same service. That is, if your service is running on 1000 nodes, all will authenticate as the same service (use the same PsEPRServiceIdentity parameters. A receiver can tell the separate instances of the service apart since each will have a random instance code generated. This instance code is seen in the from/instance element of received events. [Note: an application can specify an instance string if necessary. Normal usage is to use the default random string.]

Events can be sent at any time onto any channel. To send an event, one creates a payload, creates an PsEPREvent, adds the payload to it and then sends the event on the previously opened PsEPRConnection.

PsEPREvent has methods for the fixed event values (to and from fields) and an instance of a payload. The payload is encapsulated in an object that is derived from Payload.

The code for sending an event which contains an attribute payload is:

// create and populate the attribute payload
PayloadAttribute myPA = new PayloadAttribute();
myPA.setAttributeName("projectName");
myPS.setAttributeValue("Cute Service");

// create the event
PsEPREvent myEV = new PsEPREvent();
myEV.setDistribution(PsEPREvent.distributionOne);
myEV.toChannel("/example.com/services/cuteservice/status");
myEV.toService(myService);    // optional
myEV.toInstance(myInstance);  // optional
myEV.setPayload(myPA);
myPConn.sendEvent(myEV);
          

Note that you do not specify the from fields of the event. These are set by the PsEPR infrastructure based on the authenticated identity that was used to create the connection.

SendOneEvent soe = new SendOneEvent();
PsEPREvent pe = new PsEPREvent();
PsEPRServiceIdentity id = new PsEPRServiceIdentity(service, password);
pe.setChannel(channel);
... initialize the PsEPREvent
String myPayload = "";
Payload pl = new PayloadGeneric();
pl.setXML(myPayload);
pe.setPayload(pl);
soe.sendOneEvent(i, pe);
              

To receive and event, one must get a lease on a channel for messages of a particular type. The lease request

import org.psepr.jClient.*;
class PayloadMyPayload extends Payload implements PayloadParser {
  public PayloadMyPayload() {
    super("myPayloadNamespace");
  }

  // get and set varaibles that access the data in the payload
  ...

  // method that parses the payload
  public Payload parsePayload(String ns, XmlPullParser parser) {
    // check to make sure the name space matches.
    if (ns.equalsIgnoreCase(super.getNamespace())) {
      // parse the payload leaving the parser on the ending payload element
      myPayload = new PayloadMyPayload();
      ...
      return myPayload;
    }
    return null;   // null to denote that we didn't parse the payload
  }

  // method that outputs an XML representation of the payload
  //   note that is includes the beginning and ending payload elements
  public String toXML() { }
}
              

PayloadParser myPP = new PayloadGeneric("/my/name/space");
myPLease = myPCon.getLease(channelName, myPP, this);
...
public boolean receiveEvent(PsPEREvent ev) {
  if (ev.getPayload() != null) {
    if (ev.getPayload() instanceOf PayloadGeneric) {
      System.out.println("Body of payload in XML = "
              +((PayloadGeneric)ev.getPayload()).getXML());
      }
    }
  }
}
                

EventQueue eQueue = new EventQueue();
PsEPRLease lease1 = pConn.getLease(chan1, parser1, eQueue);
PsEPRLease lease2 = pConn.getLease(chan2, parser2, eQueue);
...
              

// user supplies their own lease manager
PayloadParser mpp = new ClassThatImplmentsPayloadParserInterface();
EventReceiver mer = new ClasstheImplementsPayloadReceiverInterface();
LeaseManager mem = new ClassDerivedFromLeaseManager
PsEPRLease lease1 = pConn.getLease(chan1, mpp, mer, mem);

// use the SimpleLeaseManager for a lease of 300 seconds
PayloadParser mpp = new ClassThatImplmentsPayloadParserInterface();
EventReceiver mer = new ClasstheImplementsPayloadReceiverInterface();
LeaseManager mem = new SimpleLeaseManager(300);
PsEPRLease lease1 = pConn.getLease(chan1, mpp, mer, mem);
                
// use the SimpleLeaseManager for a lease of 300 seconds
PayloadParser mpp = new ClassThatImplmentsPayloadParserInterface();
EventReceiver mer = new ClasstheImplementsPayloadReceiverInterface();
PsEPRLease lease1 = pConn.getLease(chan1, mpp, mer, 300);
                
// use the SimpleLeaseManager for the default period
PayloadParser mpp = new ClassThatImplmentsPayloadParserInterface();
EventReceiver mer = new ClasstheImplementsPayloadReceiverInterface();
PsEPRLease lease1 = pConn.getLease(chan1, mpp, mer);
              

<SimpleLeaseManager>
    <MaximumRetires>3</MaximumRetires>
    <-- default duration in seconds -->
    <DefaultLeaseDuration>120</DefaultLeaseDuration>
    <-- seconds to wait for lease confirmation -->
    <ShortTimeoutAbsolute>20</ShortTimeoutAbsolute>
    <-- percent of duration to wait before renegotiating the lease -->
    <LongTimeoutPercent>80</LongTimeoutPercent>
</SimpleLeaseManager>
              

LeaseHandler inLease = null;
try {
  PayloadParser xParser = new PayloadGeneric();
  EventQueue eQueue = new EventQueue();
  String myChannel = "/edu/usgsr/grad/topoWatch/status/";
  // pConn is an open PsEPRConnection
  // note the use of 'null' for the LeaseWatcher callback
  inLease = new LeaseHandler(pConn, myChannel,  xParser, eQueue, null);
  // leases are not instantanious so we wait for it to be granted
  inLease.waitForLease();
}
catch (PsEPRException e) {
  System.out.println("GetLease failed:"+e.toString());
  pConn.close();
  return;
}
catch (Exception e) {
  // I don't know why this would happen
  System.out.println("GetLease exception:"+e.toString());
  pConn.close();
  return;
}
                

The parsing of the XML is done with a "pull parser". The whole message is not parsed initially into DOM objects nor are events passed for the elements (al la SAX), but a parser moves through the XML and the application looks at the elements as they pass by.

The pull parser used in jClient is available at http://xmlpull.org/ where there are the jar files, an introduction to the library and Java API documentation.

The general form for parsing payloads is the following (using the attribute payload as an example):

public Payload parsePayload(String ns, XmlPullParser parser) {
  PayloadAttribute myPA = null;
  if (ns.equalsIgnoreCase(attributeNamespace)) {
    try {
      myPA = new PayloadAttribute();
      boolean done = false;
      while (!done) {
        int pI = parser.next();
        if (pI == XmlPullParser.START_TAG) {
          String elementName = parser.getName();
          if (elementName.equals("field")) {
            myPA.setAttributeName(PsEPRService.cleanXMLText(parser.nextText()));
          }
          if (elementName.equals("value")) {
            myPA.setAttributeValue(PsEPRService.cleanXMLText(parser.nextText()));
          }
        }
        else if (pI == XmlPullParser.END_TAG) {
          if (parser.getName().equals("payload")) {
            done = true;
          }
        }
      }
    }
    catch (Exception e) {
      // if the parser exploads, we have to bail
      throw new PsEPRException("PayloadLease parser failed: "+e.toString());
    }
  }
  return myPA;
}
          

• The parser routine is entered pointing at the payload start element so attributes can be fetched;
• The routine must exit with the parser pointing at the payload END_TAG
• the parser is advanced by calling next() or nextText(). Validation is not done and parsing can be pretty free form (note that this doesn't check for the end elements for field or value, for instance);
• the cleanXMLText() utility routine cleans out the end-of-line characters and removes white space around the value. This could result in a zero length string or a null (if there was no text). But, in general, what happens is what is expected;
• if anything fails in the parsing, this throws an Exception. Because there is no way to back out of parsing, the event is lost and no further processing will happen after this Exception.

There are some environmental parameter defaults that can be set with a configuration file. The configuration file is named .PsEPRjClient.xml and is looked for in the following directories in the following order:

The configuration file is an XML file. A full blown, fully specified file looks like:

<jClient>
    <router>
        <!-- the number of times to retry the connectin to the router -->
        <reconnectionRetries>5</reconnectionRetries>
        <!-- milliseconds to wait for XMPP connection and login responses-->
        <connectionTimeout>10000</connectionTimeout>
        <!-- expiration seconds for jabber messages -->
        <defaultExpiration>30</defaultExpiration>
        <!-- optional default SOCKS service to use -->
        <!-- if specified, this SOCKS service is used for all routers below -->
        <socks>
            <server>5222</server>
            <port>5222</port>
        </socks>
        <r001>
            <name>psepr_router</name>
            <server>jabber.services.planet-lab.org</server>
            <instance/>
            <!-- JID address of routers: usually combination of above -->
            <address>psepr_router@jabber.services.planet-lab.org</server>
            <!-- optional port specification -->
            <port>5222</port>
            <!-- optional per router SOCKS connection specification -->
            <socks> 
                <server>5222</server>
                <port>5222</port>
            </socks>
        </r001>
        <r002>
            <!-- the minimun that must be specified -->
            <server>planetlab2.cs.purdue.edu</server>
        </r002>
    </router>
    <!-- optional section the just specifies the name of the registry -->
    <registry>
        <r001>
            <name>psepr_registry</name>
        </r001>
    </registry>
    <!-- optional serviceID information used as a default by some tools -->
    <!-- As mentioned above, this should be in user local config files. -->
    <default-service>
      <service>myservice</service>
      <password>nooneknowsit</password>
    </default-service>
    <!-- parameters for the default simple lease manager -->
    <SimpleLeaseManager>
        <MaximumRetires>3</MaximumRetires>
        <!-- default duration in seconds -->
        <DefaultLeaseDuration>120</DefaultLeaseDuration>
        <!-- seconds to wait for lease confirmation -->
        <ShortTimeoutAbsolute>20</ShortTimeoutAbsolute>
        <!-- percent of duration to wait before renegotiating the lease -->
        <LongTimeoutPercent>80</LongTimeoutPercent>
    </SimpleLeaseManager>
    <debug>
        <!-- 'on' if to output all sent and received packets -->
        <detailedPacketPrintout>off</detailedPacketPrintout>
        <!-- controls the output of the debug logger -->
        <filterLevel>
            <!-- default filter output level -->
            0x0000
            <!-- filter flags for individual modules -->
            <modulename>0xFFFE</modulename>
        </filterLevel>
    </debug>
</jClient>
          

The specification of debug output is a bit array. The value given outside any modulename block is the default value that will be used everywhere. If a modulename block is given, the debug value applies only to that logging module. The bits have the following meaning:

Because most of the values default, the absolute minimum configuration file only needs to list the routers to connect to:

<jClient>
    <router>
        <r001>
            <server>jabber.services.planet-lab.org</server>
        </r001>
        <r002>
            <server>planetlab2.cs.purdue.edu</server>
        </r002>
        <r003>
            <server>router.example.com</server>
        </r003>
        <r004>
            <server>router.example.de</server>
        </r004>
    </router>
</jClient>
          

ArrayList<String> userConfigs = new ArrayList<String>();
...
for (int jj=0; jj<args.length; jj++) {
    ...
    if (args[jj].equalsIgnoreCase("--config") {
        userConfigs.add(args[++jj]);
    }
    ...
}
...
if (userConfigs.size() > 0) {
    PsEPRService.setConfigFiles((String[])userConfigs.toArray());
}
...
PsEPRConnection pConn = new PsEPRConnection(...);
...
              

The configuration file lists several PsEPR Routers that the library can connect to. When a new PsEPRConnection is created, one of these Routers is chosen. What follows is a description of how that is done within the library and how it can be extended.

When a new PsEPRConnection is created, it calls PsEPRService.getRouterManager().getNextRouterToTry(). This routine, a method of the RouterManager interface, returns an instance of the class PsEPRRouter. PsEPRConnection tries to connect to the specified Router and if it fails, it calls PsEPRServcice.getRouterManager().routerFailed() with the router that didn't work. It then calls getNextRouterToTry() to get another router.

In this way, PsEPRConnection steps through all the potential Routers to find one that is working.

If a RouterManager is not set before the first creation of a PsEPRConnection, an instance of SimpleRouterManager is created. SimpleRouterManager implements a weighting of the routers: successful connections add to the weight and time decreases the weight. The current values of the weights are saved in the file /usr/local/psepr/etc/jClientRouterInfo.xml or \Documents and Settings\USER\.psepr\jClientRouterInfo.xml depending on the OS. The routers listed in jClient.xml use the saved weight valued from these files to probablistically choose the routers to return as getNextRouterToTry() is called. Nothing bad happens if these files are missing -- it just might take longer to connect next time.

This selection process can be extended by providing a user created class which implements the RouterManager interface. Before the first PsEPRConnection is created, the calling routine can set a manager by calling PsEPRService.setRouterManager() passing a class which implements the RouterManager interface. The user's manager then returns Routers to PsEPRConnection based on any criteria it wishes (locality to calling host, existance of existing connections, etc).

Schemas are available for some of the PsEPR XML items. Here is the current list: