Pronto Control

Pronto includes a module that allows a Java application to be controlled with externally supplied instructions. It depends on the state module to provide the abstraction through which an application is controlled. The module currently provides three different control mechanisms that can be freely combined. They are:

STDIN (System.in): Instructions may be received via STDIN. This allows an application to respond to directives from a user at a console, or shell pipe.
File: Instructions may be supplied to an application within a file. The file is continually polled by the control module for new instructions. This provides a simple way for other applications running on the same machine to control a Java application.
Signal: A limited degree of control is available when a JVM is terminated (eg. by a user typing Ctrl-C at a console). The control module is able to automatically navigate into a terminal-state for the graph.

Usage

The Controller is the core class within the control module. Controllers use state engines as an mechanism to communicate control events to application. The following documentation assumes familiarity with state module. There are three basic steps in using a controller.

Creating a settings object that defines the controller parameters.
Creating a controller by supplying the settings to a factory.
Starting the controller (to begin monitoring the application's environment).

1. Creating a control settings object

The settings for a controller are provided by the application through the satisfaction of an interface (in the spirit of the configuration module). All are extensions of com.tomgibara.pronto.control.ControllerSettings. There is one interface for each type of control that is supported by the module. A settings object may implement one or more of these interfaces. The currently supported interfaces are:

com.tomgibara.pronto.control.StdinControllerSettings
com.tomgibara.pronto.control.FileControllerSettings
com.tomgibara.pronto.control.SignalControllerSettings

2. Creating a controller

Controllers are created using the factory class com.tomgibara.pronto.control.ControlFactory. The factory is a singleton that is obtained by calling its getInstance() method. The factory supports two methods: one for checking whether a given interface is supported (to enable future extensions to the module), and another to create a Controller.

Three parameters are required to create a controller. These are:

The settings object - this specifies the parameters of external application control.
A state engine - this determines the state of the application; the engine is expected to be shared with other elements of the application that may independently control its state (naturally not all control of an application need be externalized).
An engine control adapter - this allows elements of the state engine (labels, states and parameters) to be converted to/from their string representations; necessary for reading input from files and STDIN.

Any number of controllers may be created from the factory.

Note: at present the control module permits multiple controllers to read STDIN without 'sharing' input between them (each will compete for input). For the present creating a multitude of such controllers should be avoided. This shortcoming will be resolved in a future release.

3. Starting the controller

Each Controller is created in passive state; a controller will not start to monitor an application's environment for control instructions until it is started. Starting a controller is simply a case of calling the start method. Controllers may also be stopped (and restarted). They are entirely safe for multithreaded use.