This is an old revision of the document!


Quickstart

Use the TimEL facade to compile and run a program:

// Assemble the evaluation interval as [now, now + 1 second)
long now = new Date().getTime();
 
Interval interval = Interval.of(now, now + 1000L);
 
// Compile the expression 1 + 1
Expression<Double> expression = TimEL
    .getCompiler("1 + 1") // Get the compiler builder for the expression 1+1
    .compileExpression(Types.getNumericDoubleType()); // Compile the source as an expression 
                                                      // that returns a double
 
// Execute the expression
TimeIterator<Double> itor = TimEL
    .getExecutor(expression) // Get executor for the expression
    .evaluateFor(interval); // Evaluate for the given interval
 
// Since 1+1 is constant we'll have a single sample for the whole interval
double v = itor.next().getValue();

Note that all the job is done through the TimEL facade, first compiling the expression and then executing it.

The following example shows how to provide non constant values to TimEL using a *variable*.

// Create a new variable backed by a TreeMap
TreeMapVariable<Integer> variable = new TreeMapVariable<>();
TreeMap<Interval, Integer> values = variable.getTreeMap();
 
// Add some values to the variable:
Instant now = Instant.now();
for(int[] i : new int[][] {{0, 1, 1}, {1, 2, 2} /* Gap */, {2, 3, 4}})
    values.put(Interval.of(
            now.plus(i[0], ChronoUnit.MINUTES),
            now.plus(i[1], ChronoUnit.MINUTES)
    ), i[2]);
 
// Compile "a * a"
Expression expression = TimEL
        .parse("a * a")
        .withVariable("a", new IntegerType(), variable) // Declare 'a' as a int
        .compile();
 
// Evaluate the expression in the interval [now, now + 5 minutes)
TimeIterator<Double> itor = TimEL
        .evaluate(expression, Interval.of(now, now.plus(5, ChronoUnit.MINUTES)));
 
// Pull the results, effectively evaluating the expression.
// This will print 3 lines, one for each interval, with the value 1, 4 and 16.
while(itor.hasNext())
    System.out.println("\t" + itor.next());

Note that TimEL works in a streaming way, that is it pulls values from input and computes the result as soon as the output iterator is advanced. This way allows the library to work incrementally, thus the whole dataset is not required to fit in memory (imagine having various year of samples at a second resolution!) but can be instead streamed when needed.

To provide values to a TimEL program or expression the followings steps are needed, as shown above:

  1. The variable needs to be declared at compile time with its relative type;
  2. An instance of the variable needs to be bounded at execution time.

TimEL is agnostic to data storage and requires the user to implement the Variable interface to allow read and write operations. Note that reading an interval in both directions is required.

The commodity TreeMapVariable class is a Variable implementation backed by a TreeMap can be used when the dataset is not large.

Please consider the API not mature yet and subject to change. Although no major changes are expected in the TimEL facade, the type mechanism is still prototypal an might be subject to changes.

Anything in the impl package is to be considered private, and therefore, unstable.

  • quickstart.1557427570.txt.gz
  • Last modified: 2019/05/09 18:46
  • by admin