Specification

A xbook engine is the entity that the xbook server will invoke to execute a particular type of xbook. In other words, it acts as an intermediary between the portlet client and the xbook. An engine can define its own specification for a xbook but must provide the following interface:

initialize(xbookPath, engineArgs)

This routine is called when the engine is first instantiated for a particular xbook (i.e., is the engine constructor). The user should stick any engine setup code here (e.g., initializing a interpreter). the xbookPath is the location of the xbook and engineArgs are any configuration information that is read in from the registry.

start(out)

This routine will also be called after the engine is instantiated (i.e., after initialize). This will call the xbook initialization method. Any output which the xbook wants displayed to the user should be written to the out stream. If the user expects user input, html input tags should be written to out to collect them.

stop(out)

This routine will be called with the engine is shutdown. Any cleanup code should be put here (i.e., shutting down an interpreter). Any output which the xbook wants displayed to the user should be written to the out stream.

execute(command, formValues, out)

This routine will be called when the user presses a submit button from the portlet and can be called multiple times. The name of the submit button and any form parameters are sent as input. The engine will then call the appropriate xbook method to handle the input. Any output which the xbook wants displayed to the user should be written to the out stream. If the user expects further user input, html input tags should be written to out to collect them.

Figure 2.2 illustrates a sample xbook session with one xbook method being called.

Figure 2.2: Sample xbook session.

The engine itself must be written in Java but the xbook itself can be written in any desired scripting language. In our first implementation, we target jython but engines can also be written to handle xbooks in python, csh, perl, etc.

A xbook session is considered active when the xbook sends a keep_alive hidden input form parameter in the out stream. During an active xbook session, the engine is responsible for maintaining state between a multi-stage request (i.e., calling execute multiple times). In the jython engine, this translates to executing the jython scripts under the same interpreter.

The jython engine is further described in Section 2.2.6.6.