The Theseus Java API

What is the Theseus API?
How do I use it?
API Documentation

1. What is the Theseus API?

Included in the Theseus release is an API that allows you to easily incorporate Theseus functionality into your existing Java applications. Using the Theseus API involves calling a special library function with a plan (in plaintext or in a file) and input data (in plaintext or as Relation objects) and then unwrapping its output.

2. How do I use it?

To use the Theseus API, you simply need to do the following:

Import the following libraries:
- theseus.api.AttrList
- theseus.api.LoadedPlan
- theseus.api.Relation
- theseus.api.RelationList
- theseus.api.Theseus
- theseus.api.Tuple
Instantiate a Theseus object.
Load a plan via the loadPlan() method.
Call the executePlan() method on the Theseus object, specifying input preferences (Reader or RelationList objects).
Unpack the Relation objects in the RelationList returned.
Shutdown the Theseus subsystems by calling shutdown().

As an example, consider the following code:

import theseus.api.AttrList;
import theseus.api.LoadedPlan;
import theseus.api.Relation;
import theseus.api.RelationList;
import theseus.api.Theseus;
import theseus.api.Tuple;

import java.io.StringReader;

/*
 * A very simple example of using the Theseus API
 */
public class Example
{
  public static void main(String[] args)
  {
    try {
      String plan = "PLAN p { INPUT: stream s1, stream s2 "+
        "OUTPUT: stream s3 BODY { union (s1, s2 : s3) } }";

      RelationList inRel = new RelationList();
      Relation cur;

      AttrList aLst1 = new AttrList("name char");
      cur = new Relation("s1", aLst1);
      cur.addTuple(new Tuple(aLst1, "Lucy"));
      cur.addTuple(new Tuple(aLst1, "Ricky"));
      inRel.addRelation(cur);

      AttrList aLst2 = new AttrList("name char");
      cur = new Relation("s2", aLst2);
      cur.addTuple(new Tuple(aLst2, "Fred"));
      cur.addTuple(new Tuple(aLst2, "Ethel"));
      inRel.addRelation(cur);

      Theseus th = new Theseus();
      LoadedPlan lp = th.loadPlan(new StringReader(plan));

      RelationList outRel = th.executePlan(lp, inRel);
      if (outRel != null) {
        for (int j=0; j<outRel.size(); j++) {
          System.out.println(outRel.getRelation(j));
        }
      }

      th.shutdown();

    }
    catch (Exception e) {
      e.printStackTrace();
    }
  }
}

When this code is run, the following is output:

name=[p_i1_s3], attrs=[name char], values=[Ethel, Lucy, Fred, Ricky]

Notice that all that was necessary was to (a) create the Theseus object, (b) load the plan, and (c) call the Theseus excute() method, supplying the loaded plan reference and an array of Relation input objects. It is also important to call the shutdown() method on the Theseus object, since Theseus keeps threads alive (outside of programmer control) until shutdown() is called.

The complete code for this example can be found in the "src" directory of your Theseus installation.

3. API Documentation

Complete API documentation for Theseus is available.

The Theseus Java API

Contents

1. What is the Theseus API?

2. How do I use it?

3. API Documentation