FIRST JavaSpaces PROGRAM (HELLO WORLD)

Frans Coenen

1. INTRODUCTION

In this WWW page we will describe a simple "HelloWorld" JavaSpaces application comprising a single process. We will commence by introducing and discussing some details concerning JavaSpaces concepts: entries (Section 2), operations on entries (Section 3), the SpaceAccessor class (Section 4) and templates (Section 5).

NOTES: For information on compiling JavaSpaces programs, usin refer back to spacesIntro.html.



2. ENTRIES

A space is a shared repository for entries. An entry is a collection of typed objects that implement the Entry "marker" (empty) interface. Example:

import net.jini.core.entry.*;

/* ----------------------------------------- */
/*                                           */
/*               MESSAGE CLASS               */
/*                                           */
/* ----------------------------------------- */

public class Message implements Entry {

    // Fields

    public String content;

    // Constructors

    public Message() {
        }

    public Message(String content) {
    	this.content = content;
	}

    // Methods

    public String toString() {
  	return("Message is: " + content);
	}
    }

Table 1: Message class (based on that contained in Freeman et al. 1999).

Note that the fields are public so that they can be accessed.



3. WRITE, READ AND TAKE

Three principal operations can be performed on objects in spaces:

Lease write(Entry e, Transaction txn, long lease);
Entry read(Entry tmpl, Transaction txn, long timeout);
Entry take(Entry tmpl, Transaction txn, long timeout);

which perform the following.

  1. Write a new object into a space
  2. Read (make a copy of) an object from a space
  3. Take an object from a space

e is the entry name. txn indicates the nature of the transaction security, for the time being we will set this to null. lease is the requested lease time for the entry and specifies how long the object should exist in a space, this may be a time in milli-seconds or be set to Lease.FOREVER. The actual lease granted by a space as a result of a write is returned by the write method.

read and take have the same type of arguments, and both return an instance of the class Entry. The first argument is a template (see below) and for the time being we will set the transaction security to null. The argument is a "time out" parameter specified in milliseconds or set to Long.MAX_VALUE or JavaSpaces.NO_WAIT. This is the time that the read/take method will wait if no entry matching the given template is found.

Both read and take are "blocking operations" --- if no matching entry exists the methods will wait according to the time out value, for an appropriate entry to arrive. Non-blocking versions exist: readIfExists and takeIfExists.

The above are all instance methods of the class JavaSpace. Thus to use these methods we must create a JavaSpace object which will allow access to a space.



4. ACCESSING A SPACE

To access the space we will make use of the SpaceAccessor class described in spaceAccess.html and contained in the JavaSpacesUtil package. From inspection of this class it can be seen that to access a space we use the getSpace instance method.

We are assuming here that we wish to access the space named in the property file, i.e. frans_space.



5. TEMPLATES

To read an entry a template is used. A template is an entry which can have one or more of its fields set to null. An entry matches a template if:

  1. The entry has the same type as the template (or is a subtype), and
  2. For every specific (non null) field in the template their fields match exactly (the null fields act as "wildcard" fields).

This means, of course, that we can not match on "nulls", but there are ways round this. Note that matching is only done on object fields. An application that makes use of a template to obtain a Message entry (see above) is as follows:

/* ----------------------------------------- */
/*                                           */
/*                 HELLO WORLD               */
/*                                           */
/* ----------------------------------------- */

// JavaSpacesUtil package

import JavaSpacesUtils.SpaceAccessor;

// Jini core packages

import net.jini.core.lease.*;

// Jini extension package

import net.jini.space.JavaSpace;

public class HelloWorld {

    /* ------ METHODS ------ */
        
    /* MAIN */
    
    public static void main(String[] args) {
        System.out.println("START");
		 
        // try block
        try {
	    // Create Message object entry
	    System.out.println("Create Message entry");
	    Message msg = new Message("Hello World");
	    // Get JavaSpace     
	    SpaceAccessor newSpaceAccessor = new 
	    		SpaceAccessor("/home/staff5/ra/frans/JavaProgs/" +
				"JavaSpaces/JavaSpacesUtils/frans_space.prop");
	    System.out.println("Get JavaSpace");
	    JavaSpace space = newSpaceAccessor.getSpace();
	    // Send Message entry into space
	    space.write(msg,null,Lease.FOREVER);
	    // Create a template
	    Message template = new Message();
	    // Read message and output	
	    Message result = (Message) space.read(template,null,Long.MAX_VALUE);
            System.out.println(result);
	    }
	// Catch block
	catch(Exception e) {
	    e.printStackTrace();
	    }
        
	System.out.println("END");
	System.exit(0);
	}
    }

Table 2: HelloWorld class

The process in Table 2 creates a Message entry, writes it into space and then reads it back using a template. Note that the code imports the SpaceAccessor class from JavaSpacesUtil package described in spaceAccess.html. The string frans_space.prop is the name of the property file containing details of the space we wish to use. Further details on property files an be found at spaceAccess.html.

An extended version of the above can be found at HellowWorld2.



REFERENCES

  1. Freeman, E., Hupfer, S. and Arnold, K. (1999). JavaSpacesTM Principles, Patterns and Practice. Addison-Wesley.


Created and maintained by Frans Coenen. Last updated 24 June 2002