Walking through the ChronoDB demo (1/2)

---

Important notice. On July 13, 2012, the ChronoDB project was renamed CrNiCKL, which is pronounced like "chronicle". All packages, demos included, have been renamed. The new project website is at http://agent.ch/timeseries/crnickl/. The old project remains accessible for a while at http://agent.ch/timeseries/chronodb/. The remainder of this article remains valid mutatis mutandis.

---

A demo package is available for downloading from the ChronoDB project website or from SourceForge. In a short series of posts I will comment on a few important details. I hope these explanations will be helpful.

Explanations will focus on the following code snippet from the static main method of StocksAndForexDemo:

// args[0] is name of parameter file with key-value pairs ... StocksAndForexDemo demo = new StocksAndForexDemo(args[0]); demo.setUpHyperSQLDatabase(); demo.setUpSchema(); // etc.

The constructor invocation new StocksAndForexDemo(args[0]) initializes a ChronoDB database, kept in a private member inside the demo:

private ch.agent.chronodb.api.Database db; The actual work is done by ch.agent.chronodb.api.SimpleDatabaseManager, which is one of the few non-interface classes in that package. It is provided to make it easier to write test cases (and demos). It sets up the database using parameters provided in a file on the file system or the class path. Here is an extract from such a file: db.name=demo db.class=ch.agent.chronodb.jdbc.JDBCDatabase session.jdbcDriver=org.hsqldb.jdbc.JDBCDriver session.jdbcUrl=jdbc:hsqldb:mem:demodb session.db= session.user=sa session.password= # etc. Parameters with names beginning with "db." are the most important: db.name names the database and must be unique within a running system; db.class names the implementation class. Although it is in principle possible to run multiple databases simultaneously, SimpleDatabaseManager currently supports only one database. Parameters beginning with "session." are specific to the JDBC implementation. Implementations more sophisticated than JDBCDatabase used in this simple demo will have more parameters, some of which are named in the interface ch.agent.chronodb.impl.DatabaseBackend.

At this point, a ChronoDB database object and a JDBC connection are ready for use but there is absolutely nothing in the database yet. In fact, the demo uses an in-memory HyperSQL database. Before the demo starts and after the demo terminates, the database does not exist. So the next step is to create the tables and indexes expected by the JDBC implementation of ChronoDB.

This is done by the method invocation demo.setUpHyperSQLDatabase() which sends SQL data definition language (DDL) statements to the database engine for execution. The DDL is taken from Resources/HyperSQL_DDL_base.sql. This file is in chronodb-jdbc-1.0.0.jar and therefore on the class path. The DDL defines all tables required by the base system, with various indexes and constraints to enforce referential integrity. Browse the SQL file if you need details. Noteworthy are the few non DDL statements at the end of the file, which initialize the database with the built-in properties needed when defining a series in a schema. These properties require in turn the corresponding built-in value types.

These value types are:

• name, a string type enforcing a minimalist naming policy
• type, for values defining the type of a series
• timedomain, a restricted type for time domains, with some predefined values: daily, datetime, monthly, workweek, and yearly
• binary, a boolean type

The properties, with their value type in parentheses, are:

• Symbol (name)
• Type (type)
• Calendar (timedomain)
• Sparsity (binary)

These value types and properties could in theory be provided virtually by the software, but in a JDBC implementation they are physically required because of referential integrity. For more information on time domains, please consult the documentation of the Time2 Library project. For more information on the other properties please consult the documentation of the ChronoDB database project.

At this point the database is ready for useful work directly related to the problem at hand: setting up the schema for the demo. This will be the subject of a forthcoming post.