The package "wrapper" contains a wrapper template that can be used to wrap any kind of computational services into CPAM compliant megamodules; this documentation contains information for how to wrap computational code (see user information) as well as as information for changing the wrapper templates (see maintenance information).

User Information

When using the wrapper templates you have to go through the following steps:

Choose the interface you are going to use
Subclass the class CPAMMegamodule
Start and register the server

Choose the interface

As this is a prototype wrapper template it offers more than one possible CPAM interface. For CPAM 2.0 you want to use the interface RMI_CPAM_V2_0 with the parameter encoding Gentype.

Subclass CPAMMegamodule

You wrap your computational code by subclasses CPAMMegamodule. The methods that you have to overwrite are:

protected void createParameters() : sets up the list of all parameters and their default values for this megamodule
protected boolean dispatchInvocation (CPAMWrapperCallbacks invocationObject, String methodname): does the computation for an invocation, writes back results and progress by calling methods of the invocationObject

Optional methods to overwrite are:

protected boolean makeEstimate(Estimates estimates, String methodname, ParamValueTableReader clientsettings) : provides cost estimates
protected void updateExecutionStatus(CPAMWrapperCallbacks invocationObject, String methodname) : provides invocation progress by calling methods of the invocationObject
protected void updateResult(String paramname, CPAMWrapperCallbacks invocationObject, String methodname) : provides progress information about results and progressive values by using methods of the invocationObject
boolean abortExecution(Invocation invocationObject, String methodname): allows you to terminate an invocation when its results are no longer required, instead of finishing it

In case the computational code provides progress information and progressive results at all: Depending on the kind of computational code it is easier to report progress when promted or when it is convenient to the computation. This wrapper allows both mechanisms. Therefore there are two ways how the computational code can provide this information, though it always uses the same methods for reporting the information:

whenever it has a new progressive result it can write back that result by using the method of the invocationObject defined in the CPAMWrapperCallbacks interface
it can wait until one of the methods updateExecutionStatus or updateResult is called, and write back the new information in these methods before returning these methods

For the methods provided to write back information to the invocationObject see the interface CPAMWrapperCallbacks. When overwriting makeEstimate, the information about which estimates are required is in estimates and the generated cost estimates also have to be stored in estimates (for details see class Estimates). If you need to know the values of the client specific settings, use the methods from the interface ParamValueTableReader on the object clientsettings.

Compiling: the wrapper templates use Java 1.2 classes, so you better use the Java 1.2 (i.e. Java 2.0) compiler!

Start the server

Setting the CLASSPATH: make sure your classpath includes the package convert needed by the interface RMI_CPAM_V2_0 (should be in /u/ftp/www/CHAIMS/Code/ASN1/Java_ASN1/), the package cpam_rmi also needed by the interface RMI_CPAM_V2_0 (should be in /u/ftp/www/CHAIMS/Code/Wrappers/RMI_Wrapper/Vers_2_0), and the package wrapper. Also make sure LD_LIBRARY_PATH includes /u/ftp/www/CHAIMS/Code/ASN1/Java_ASN1/convert.

Make sure the rmi registry is started on the computer where you want to start the server (unix command rmiregistry).

The main method in class RMI_CPAM_V2_0 creates an instance of your megamodule and registers the megamodule with the registry. RMI_CPAM_V2_0 takes three arguments: "Gentype" (specifies that you are using the wrapper template for an interface using Gentypes), the name of the subclass of CPAMMegamodule that you created, the name of the megamodule as it appears in the CHAIMS repository.

java wrapper.RMI_CPAM_V2_0 Gentype TestModule2 Module2

Maintenance Information

not yet written

Interaction diagrams for some of the CPAM primitives, and a class diagram can be found here (not yet made).

Compiling and documenting

Use the java 2.0 compiler. Do not forget to document your updates!!! To regenerate automatically the documentation use the following command in the parent directory of the wrapper package:

javadoc -d Doc -use -private -nodeprecated -nohelp
-windowtitle "CHAIMS Java wrapper template documentation" wrapper