Chapter V. Extending Cassandra PV Archiver

Table of Contents
1. Adding a control-system support

The Cassandra PV Archiver has been designed to be modular, so that it can easily be extended. The standard distribution is built from five Maven modules:

The cassandra-pv-archiver-common module provides code that is shared by most modules, in particular some utility classes. For details please refer to the API reference.

The cassandra-pv-archiver-control-system-api module provides the API classes that have to be implemented by a control-system support. Please refer to Section 1, “Adding a control-system support” and the API reference for details.

The cassandra-pv-archiver-control-system-channel-access module provides the control-system support for integration with Channel Access based control-systems. Please refer to Appendix D, Channel Access control-system support and the API reference for details.

The cassandra-pv-archiver-server module provides the actual Cassandra PV Archiver server. When building a custom server application, one will typically build on top of this module. For details please refer to the API reference.

The cassandra-pv-archiver-server-app module bundles the cassandra-pv-archiver-server module with the cassandra-pv-archiver-control-system-channel-access module. This module can be used as an example of how to build a custom distribution of the Cassandra PV Archiver server that contains additional control-system supports.

Instead of using the existing code for accessing the archive, some applications might want to access the database directly. In this case, please refer to Appendix A, CQL table layout for details about the database structure.

1. Adding a control-system support

The most common extension to the Cassandra PV Archiver is an additional control-system support. A control-system support provides the connectivity to a certain control-system so that process variables from that control-system can be archived. This section explains the basics of how a control-system support is implemented and registered with the Cassandra PV Archiver server. It is intended as an addendum to and not a replacement of the API reference, which should also be studied carefully.

The entry point for a control-system support is its implementation of the ControlSystemSupportFactory interface. Each control-system support has to provide such an implementation and register it by adding the file META-INF/cassandra-pv-archiver.factories to the class path. This file should contain a single entry for registering the ControlSystemSupportFactory:

com.aquenos.cassandra.pvarchiver.controlsystem.ControlSystemSupportFactory = \
  com.example.MyControlSystemSupportFactory

This file is a Java properties file and thus has to adhere to the syntax expected by the java.util.Properties class. In this example, com.example.MyControlSystemSupportFactory is the factory class for the new control-system support.

The factory class has to provide the prefix that is used to identify configuration options in the controlSystem section of the server’s configuration file. In addition to that, it provides a method for instantiating the actual control-system support class (which has to implement ControlSystemSupport). While the factory needs to have a default constructor, the actual control-system support can be initialized using the control-system options that have been specified in the server’s configuration file.

The control-system support is identified by an identifier and a name. The identifier is used in configuration files (when importing or exporting channels) and in the database. The name, on the other hand, is displayed to the user in the administrative user interface. It is important that the identifer for a control-system support does not change after its first release because existing channels using the control-system support would otherwise become unusable. The name, on the other hand, is only used for informational purposes and can thus be changed at a later point in time without having any impact on existing channels.

The control-system support has to implement methods for creating a channel (so that the corresponding process variables is monitored for changes), writing single samples, and reading samples from a single sample bucket. Each control-system support uses at least one table for storing its samples. This table should be created when instantiating the implementation of the ControlSystemSupport interface for the first time. For details about the methods that have to be implemented, please refer to the API reference.

Unless explicitly specified otherwise, all methods of a control-system support are expected to not block. Operations that may not be able to finish instantly (e.g. retrieving data from the database) return a Future that finishes asynchronously. This design has been chosen to allow the parallel processing of many channels without having to use a very high number of threads. You might want to study the code of the Channel Access control-system support as an example of how such an implementation might work.