Thermostat/StatementDescriptors

From IcedTea

Jump to: navigation, search

Thermostat Home

Contents

1 Statement Descriptors

If you are a Thermostat developer you might find the following brief introduction to Thermostat statement descriptors helpful. What are Statement Descriptors in Thermostat? Since Thermostat is a database-backed application it uses "statements" for manipulating data in the database. Statement Descriptors are an abstract String representation of such statements.

1.1 Statement Types

There are 6 types of Statements in Thermostat:

  1. ADD
  2. REMOVE
  3. UPDATE
  4. REPLACE
  5. QUERY
  6. QUERY-COUNT

ADD, REMOVE, UPDATE, and REPLACE are write operations. QUERY and QUERY-COUNT are read operations. ADD is an "insert" in SQL speech. REMOVE deletes matching records if any. UPDATE allows for updates of specific Keys in a Category. REPLACE is a special form of write. It either updates an existing record, or adds a new one if it doesn't exist. QUERY-COUNT can be thought of as "count(*)" in SQL speech.

1.2 Free Variables

Thermostat's Statement Descriptors may contain free variables. That is, free variables can be set via PreparedStatement.set*() methods. There are the following supported types for free variables:

Java Type Token in Statement Descriptor
boolean ?b
Array of boolean ?b[
long ?l
Array of long ?l[
int ?i
Array of int ?i[
String ?s
Array of String ?s[
double ?d
Array of double ?d[
Pojo ?p
Array of Pojo ?p[

1.3 Statement Descriptor Format

The Statement Descriptor Format is fairly simple DSL. Tokens are separated by white-space (this is important!). In general descriptors follow a certain pattern. The pattern is dependent on the statement type. Here are a few examples.

ADD agent-config SET 'agentId' = ?s , 'startTime' = ?l , 'stopTime' = ?l , 'alive' = ?b , 'configListenAddress' = ?s

Add statement types require all Keys of the Category to be specified. Note that the set list above is of the format: keyName equals value comma keyName equals value. ALL tokens separated by whitespace (even the comma). Limit and sort expressions don't make sense for ADD's. An attempt to parse such a descriptor will fail. A query on the same Category could look like this:

QUERY agent-config WHERE 'startTime' = ?l AND 'stopTime' <= ?l SORT 'startTime' DSC LIMIT ?i

In query statements where conditions are allowed. There may be more than one condition. Every condition has to be separated via logical connectives. Logical connectives follow the usual logic precedence rules. Free variables are allowed almost anywhere. Here is another query example.

QUERY foo WHERE 'a' = 'b' OR NOT 'c' = ?b OR 'e' < 'f' OR 'g' >= ?i AND NOT 'x' = 'y' AND 'u' = 'w' AND 's' = ?s

Replace statement types can be thought of an update on all Keys in a Category or an ADD if the record does not exist. As such REPLACE, usually have a condition to it and require all key values to be specified. Contrived example:

REPLACE agent-config SET 'agentId' = ?s , 'startTime' = ?l , 'stopTime' = ?l , 'alive' = ?b , 'configListenAddress' = ?s WHERE 'alive' = false

Update statements allow for a subset of Keys to be updated:

UPDATE agent-config SET 'agentId' = 'fooBar' WHERE 'agentId' = 'barbara'

Single quotes indicate a literal string. In Thermostat, literal strings on the left hand side of an assignment are treated as Keys (identified by their name). Feel free to browse the Thermostat code for more statement descriptor examples. Feel free to contact us on the mailing list if you have trouble getting a descriptor right.

Personal tools