EQUIP4J

This is the tutorial for Equip4j. In a few words equip4j implements (and not only) the concept of dataspace. A dataspace may be interpreted as a middleware solution for distributed computing.

Equip4j is a Java library developed for the Equator project (http://www.equator.ac.uk/). The source code can be found at http://sourceforge.net/projects/equip.

How does it work?

Basically, equip4j provides a Java library that exploits the concept of dataspaces. One way to view the way equip4j works is by the three roles of software components: the server, the consumers and the producers. The consumers can make subscriptions to any kind of tuples(1), the producers post tuples (or updates to these) to the server (2), and the server processes and notifies the consumers about new tuples (3,4). Any software component may assume the consumer or producer role.

For ease of implementation, Equip4j provides libraries for handling, managing and distributing tuples through the JavaBean framework. Most of the documentation here provided deals with the libraries surrounding this particular JavaBean support in equip4j.

The Class Tuple

A tuple "is a finite sequence of objects" or elements (similar to a row in a database). In equip4j, a tuple is a generic class used to interchange information between producers and consumers. In equip there are two subclasses of tuples: Tuple and TupleEvents.

Elements in equip tuples are stored in an array. The way to create a tuple is as follows:

Tuple message =new TupleImpl(new StringBoxImpl("Chat"),
                             new StringBoxImpl("Peter"),
                             new StringBoxImpl("Hello!"),
                             new StringBoxImpl("Jane"));

This tuple can represent a chat message (Hello) form Peter to Jane. As the elements of the tuple are in an array, the order of the elements remains the same and can have meaning, i.e. the second element is the "sender of the message". Notice each element in the tuple is a subclass of the ValueBase class, in the example StringBoxImpl is used to send strings. Furthermore, the class Tuple has two other fields: name and id, the elements are stored in the field fields.

The current contructors allow a certain maximum number fields. In case you require more than the current maximum number of fields (in fields), it is possible to manipulate the field fields directly as follows:

   Tuple message =new TupleEventImpl();
   message.fields = new ValueBase[12];
   message.fields[0] = new StringBoxImpl("Chat");
   message.fields[1] = new StringBoxImpl("Peter");
   ...
   message.fields[10]= new StringBoxImpl("Hello!"),
   message.fields[11]= new StringBoxImpl("Jane");

About nulls in the fields the following are the possibilities:

  
   message.fields[0] = new StringBoxImpl("Chat");       /* Correct*/
  
   message.fields[1] = new StringBoxImpl(null);         /* Correct but DANGEROUS */
     	
   message.fields[9] = null;                            /* Correct and recommended*/

The Class DataspaceBean

The class DataspaceBean represents the server and allows the programs (consumers and producers) to communicate with the server (as a proxy). The form to create an instance of this class is as follows:

...
DataspaceBean mydataspace = DataSpaceBean();
... 
mydataspace.setDataspaceUrl("equp://127.0.0.1:9123");
...

In the example is supposed there is a equip server running at the IP address 127.0.0.1 (local machine) and at the port 9123.

The form to post a new Tuple in the server is as follows:

...
/* first create the tuple*/
Tuple message =new TupleImpl(new StringBoxImpl("Chat"),
                             new StringBoxImpl("Peter"),
                             new StringBoxImpl("Hello!"),
                             new StringBoxImpl("Jane"));
/* then, put name and id */
message.id=mydataspace.allocateId();
message.name="chat_message";
 
/* finally add the tuple to the dataspace */
... 
mydataspace.add(message);
...

If the tuple to add is an "event", must be added to the dataspace as follows:

...
mydataspace.addEvent(myeventTuple);
...

It is good idea to initialize the metadata filed of the event in case you don´t want to generate a warnig when the event is added. Two forms to initialize the metadata (merely as examples):

...
this.localGUID=mydataspace.allocateId();
...
myeventTuple.initMetadata(localGUID,false,true);
  
//or
  
myeventTuple.initMetadata(null,true,false);
...

The Interface DataspaceEventListener

This interface must be implemented by the consumers, in case the consumer wants to be notified about events, for instance, new tuples posted in the server. The method dataspaceEvent(DataspaceEvent event) must be implemented to process the events. When invoked, the dataspaceEvent receives as parameter a DataspaceEvent class. The DataspaceEvent class allows to retreive the posted tuple by the producer.

The form to implement listener is as follows:

...
class MyListener implements DataspaceEventListener (...)
...
 
public void dataspaceEvent( DataspaceEvent myevent)
...
/* process my event in case of AddEvent */
  if (myevent.getEvent() instance of AddEvent) {
     Tuple mytuple = (Tuple) event.getAddItem();
...

Notice that there exists several types of events.

Finally, the form to subscribe to events type "AddEvent" is as follows.

MyListener mylistener(...); 
...
/* the mytupletemplate represents the kind of tuples mylistener wants to consume*/
/* nulls can be used as wildcards                                     */
Tuple mytupletemplate = new Tupleimpl (new StringBoxImpl("Chat"),new StringBoxImpl("Jane"), null, null); 
mytupletemplate.name="chat_message";
...
mydataspace.addDataspaceEventListener(mytupletemplate,false, mylistener)

The code above allows mylistener to receive notifications (events) when a producer post (adds) tuples with the words "Chat" and "Jane" in the first two elemens of the array, the name equals to "chat_message" and any other information in the other fields (again, null is a wildcard).

Using equip

Running equip as server

The simply way to run equip as server is as follows:

java -cp <equip-jar-path> equip.data.server equip://<ip-address>:<portnumber>

As concrete example to run equip in the current machine (equip4j.jar must be placed in the directory where the command is executed):

java -cp equip4j.jar equip.data.server equip://:9123

Browsing the equip server

The Browser2 class allows to browse the dataspace (to know what is happening with the dataspace and to know if operations from your programs over the dataspace as events, addition of items and so on are working). The way to invoke the browser is as follows:

java -cp <path to equip4j.jar> equip.data.Browser2 equip://<ip-address>:<portnumber>

Equip external Resources

- equip4j Javadocs link http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/docs/equip4j/javadoc/index.html (the most important classes reside in the packages equip.data and equip.data.beans).
- An example of a chat program can be download at http://193.137.8.61/equip4jchatexample.zip
- EQUATOR project page http://www.equator.ac.uk/
- EQUIP and ECT source code http://sourceforge.net/projects/equip
- Chris Greenhalgh's Equator project page http://www.crg.cs.nott.ac.uk/~cmg/Equator/

References

- Wikipedia Tuple definition: Tuple