Extension programming guide

Archives installed by PageBox usually run in Java 2 sandboxes that prevent using special APIs, using Java Native Interface, accessing systems files... However in some circumstances these functions are useful and augment the value of PageBox and the issue is to provide a controlled access rather than an all or nothing access right.

PageBox extensions address this issue in two ways:

The PageBox administrator grants the permission to use extensions to archives based on their publisher (the account used to publish it) and repository (the site that deployed the archive).
The PageBox administrator may implement and always configure the extension. Therefore the extension uses special APIs, using Java Native Interface, accessing systems files... in the way defined by the PageBox administrator.

Applications

Shared computers

A first example is shared computers, for instance Common User Terminal Equipment (CUTE) and Common-Use Self-Service (CUSS) used in airports and other locations. These CUTE and CUSS may run applications from different providers. Today they usually run Windows or Swing applications that support ticket and baggage printers, card and bar code readers... These devices require application drivers that are the main reason why the applications are fat clients.

We may consider another approach where the shared computer runs a browser, a local Application server and a PageBox. Compared to a Swing application:

A browser interpreting HTML and CSS offer less flexibility in term of user interface. However this is also a good point: almost everyone has used a browser and is comfortable with HTML user interfaces.
A Web application is cheaper to design, implement and test than the equivalent Swing application. The Web application is also less demanding in term of programming and management skills. A servlet or JSP is almost independent of other servlets, JSP and classes. Some free products implements the Model View Controller paradigm and the J2EE framework handles connection pools, connectors and object recycling. You must code all these functions by yourself in a Swing application.
An application server + a browser can require more memory and a faster processor than a Swing application but the difference is usually minimal.
Today Swing applications are deployed and updated using JNLP agents like Java WebStart. PageBox deploys Web applications using the same jardiff format as JNLP. The main difference between both models is that in case of JNLP the deployment is client driven whereas in case of PageBox the deployment is repository driven. Client-driven deployment happens in bursts (for instance the Monday morning burst). Repository-driven is ordered: the Repository deploys first on some relay PageBoxes. Then the Repository and the relay PageBoxes deploy on other PageBoxes that may also be relays and so on.

This approach is suitable only if the Web application can access ticket and baggage printers, card and bar code readers... This is possible if the PageBox has one or many extensions that implement the application drivers. Extensions are computer dependent. You usually update an extension when you install a new device. Web applications are provider dependent: when you want to support a new provider on your shared computer network you create a new publisher account on your Repository and let the provider publish its Web application.

There is another aspect to consider: ticket printers for instance are expensive devices usually shared between shared computers. PageBox deployment facilitates their use. A Web application can use the PageBox API to enumerate the other Web application instances in its neighborhood and list their devices. Then the Web application can call a Web service of a neighbor that controls the needed device to require a given service (for instance a printing).

Control computers

In this example a computer controls one or many devices that may measure temperature, pressure, speed, analyze camera pictures for instance to detect intrusions...

The computer runs an Application server like Tomcat and a PageBox. The deployed Web applications implement Web services to return measures to the requestor and call Web services to send alarms. The strong points of the PageBox / Application server approach are that

This approach facilitates the development of control applications. The development is further facilitated by the PageBox API that allows enumerating the other Web applications instances deployed from the same Repository. If a new PageBox subscribes to the Repository other Web applications instances see the new Web application instances as soon as it is installed.
This approach facilitates the update of control applications
The Web application can offer a user interface. The host owner can check the information that she or he disclose and if the monitoring devices are working properly. A remote user can access to the application if she or he knows its URL and if she or he is granted access rights.
The Web application is OS and platform independent.

This approach is suitable only if the Web application can access the computer devices. This is possible if the PageBox has one or many extensions that implement the device drivers.

Example

In that perspective one of the most important sort of extension is the port (serial or parallel) extension. This sort of extension is easy to implement using the Sun’s Java Communication API. The Communication API is made of a Java archive, comm..jar and of a shared library (.so or .dll) and supports RS 232 serial ports and IEEE 1284 parallel ports. Sun provides the Solaris and Windows 32 shared libraries. Kevin Hester has written a portable Java communications API driver, RXTX, for Linux and Unix that has been successfully ported on a large number of platforms.

To illustrate the development, configuration and use of extensions we chose to write a minimal port extension. We describe in the Epimetheus documentation:

Where to download the Communication API and RXTX
How to setup the Communication API and RXTX on Windows and Linux
The implementation of our extension
How to package the extension
An example of form included in the Epimetheus application that displays the host ports

Implementation

Principle

An extension is a Web archive that contains one or more public classes that:

Implements a ExtensionIF interface
Have at least one public constructor with one or no parameter.

The ExtensionIF interface is defined like this:

public interface ExtensionIF {

public Object call(Object obj) throws Exception;

}

Therefore the public class must implement a public call method with an Object parameter that returns an object.

If the extension contains more than one public class that match the requirement each public class is declared as a separate extension in the PageBox configuration (rules.xml file), which means that the PageBox administration can give access permission to all archives for one public class and to archives published by a trusted publisher for another public class.

Documentation

The extension provider must document the public classes provided by its extension archive.

For each public class the extension provider must describe:

The public class full name (including the package names)
Potential risk: does the extension only reads data or does the extension also change some permanent data?
The public constructors that the PageBox API can call
The types of parameters supported by the call method
The object types returned by the call method

Packaging and testing

Create an archive containing the extension with the command jar cf
Write a Web Application to test the extension though the PageBox API
To test the extension configure the Application server in order to (1) give access to the extensions classes to pageboxLib classes and to (2) give access to the pageboxLib classes to the extensions classes. (1) is needed because pageboxLib classes instantiate and call the public classes and (2) is needed because the ExtensionIF class is defined in the PageBoxLib package. In the worse case you may define the extension AND the PageBoxLib archives on the CLASSPATH. We definitely recommend copying the extension AND the PageBoxLib archives in ASdirectory/shared/lib in case of JWSDP and Tomcat.
To test the extension also deploy the Web application with PageBox

We strongly recommend running the Application server in secure mode (with a limited set of permissions granted to the Web archives). For more information look at the installation guide. Grant the extension archive the same permissions as to pageboxLib in catalina.policy.

Programming

Public class

Here is an example:

package myPackage

import PageBoxLib.*;

public class MyExtension implements ExtensionIF {

public MyExtension() {

...

}

public MyExtension(ArrayList args) {

...

}

public Object call(Object parm) {

if (parm == null)

return call();

if (parm instanceof String[])

return call((String[]parm);

return null;

}

private Integer call() {

...

}

private String[] call(String[] parm) {

}

This extension can be instantiated with a constructor without parameters or with a constructor with an ArrayList parameter. The call method can take a null or a String array parameter. You can test this extension with the following code:

PageBoxAPI inst = new PageBoxAPI(workDir);

// Test the constructor without parameter

ExtensionIF ei = inst.getExtension("myExtension", null, null);

// Test the call method without parameter

Integer respi = (Integer) ei.call(null);

// Test the constructor with an ArrayList parameter

ArrayList al = new ArrayList();

...

ExtensionIF ei = inst.getExtension("myExtension", "java.util.ArrayList", al);

// Test the call method with a String array parameter

String[] parm = new String[10];

...

String[] respa = (String[]ei.call(parm);

...

Assuming that the extension is defined like this in the PageBox rules.xml:

<ext-name>serial</ext-name>

<ext-class>serialExt.Serial</ext-class>

</extension>

Notes:

In the implementation above the call method with a null parameter calls a private method without parameters that returns an Integer. The call method with a String array parameter calls a private method that returns a String parameter. This is valid though null is also a valid value for a String array. You must clearly document such aspects.
Because extension archives are loaded by the same class loader as the pageboxLib archive, public classes defined in the extension archives are visible in PageBox-installed Web applications, which means that you can use classes and interfaces defined in the extension archive as constructor and call parameters and responses.
The PageBox API doesn’t implement pooling or recycling of extension objects. In cases where the creation of the extension takes time and uses resources we suggest implementing the public class(es) as a facade and to use a factory to create contexts.