Object Tuple Manager

[back]

Instances of Java classes can also be written into the tuplespace without a need to manually serialize and unserialize them by using the OTM, an object-tuple mapper integrated into the SQLSpaces client. If a class with some fields should be converted into a tuple, you have to annotate the class with the @Tuple annotation and the fields with the @Field annotation from info.collide.sqlspaces.annotation.

Be aware that every superclass and field with a complex object of your class must also be annotated and the class needs a default constructor. You also have some options for the @Field annotation as follows:

  • name: The name that should be used for the field. By default, the name of the classes field is taken.
  • position: The position of the field's value in the tuple. By default, the positions are calculated automatically. Be aware that you don't use one position twice or specify a position out of the range.
  • setter: The name of the setter method for this field. By default, the settername is "set" followed by the name of the field.
  • getter: The name of the getter method for this field. By default, the gettername is "get" followed by the name of the field.

Now you can use the ObjectTupleSpace to write, read and take objects by calling the according methods. The object you give to the read and take method are used as templates, similar to the original read and take of tuples.

Because the tuplespace only can contain tuples, the objects will be converted into tuples representing the values of these objects. The ObjectTupleSpace converts the objects for writing as follows:

  • The first field contains the class' name
  • Annotated fields of type primitive, String, byte-array or XML are directly converted by using there value.
  • Fields with null-values are used as formal fields
  • For each other field, the value is recursively converted into a tuple and written into the tuplespace. The returned TupleID is the value of this converted tuple field (with type long).

For reading and taking, the ObjectTupleSpace creates a template tuple out of the given object. Primitive, XML, String and byte-array field values are used directly again. For complex field, the ObjectTupleSpace searches every tuple in the tuplespace representing objects that matches the field's value or every of these tuples if the field value is null. Then every combination of tuple ids found for the complex fields are set to the template tuple fields. The ObjectTupleSpace searches matching tuples and creates objects out of the found tuples.

We now examine an example. First we need three annotated classes. We have a Person with a Job, and a Student class which extends Person within the package info.collide.sqlspaces.otm.

@Tuple
class Person {
        @Field
        String name;
        public Person(String name) {
                this.name = name;
        }
        public Person() {}
        public String getName() {
                return name;
        }
        public void setName(String name) {
                this.name = name;
        }       
}
@Tuple
class Student extends Person{
        @Field
        Job job;
        //constructors, getter and setter-methods
}
@Tuple
class Job {
        @Field
        String name;
        //constructors, getter and setter-methods
}      

Let's assume the tuplespace is emtpy and new. We now want to write a student into the tuplespace.

ObjectTupleSpace ots = new ObjectTupleSpace();
Student greg = new Student("Greg",new Job("Waiter"));
Student carmen = new Student("Carmen",null);
ots.writeObject(greg);
ots.writeObject(carmen);

The ObjectTupleSpace now writes a tuple for the job with id 1, and tuples for both students, Greg and Carmen. The tuplespace now looks like this

1:<"info.collide.sqlspaces.otm.Job"|"Waiter">
2:<"info.collide.sqlspaces.otm.Student"|"Greg"|1> //1 is the reference to the the job
3:<"info.collide.sqlspaces.otm.Student"|"Carmen"| > //Carmen didn't have a job

We now want to find all Students.

ots.readAllObjects(new Student());

The answer are two students, one named Greg and one Carmen, but both with a job called Waiter. Both of them? Yes. If you write an object with a null-reference, in our context this doesn't mean the that there is no one, instead the null reference stands for all possible objects (see reverse structured naming). So the tuple for carmen matches also the query for "info.collide.sqlspaces.otm.Student"| |1. For our application, there is no special value which says "This field is empty". Please pay special attention to this.

There are two different ways for takeObject. The first way takes the tuple representing the object directly and not those representing references within, also the returned objects contains filled values. The other way is takeDeepObject. This also takes the tuples representing reference objects.