PageBox for Java: Web application deployment using Java PageBox

for
  Support     Home     Word  
 PageBox for Java 
 API 
 Demo 
 Background 
Presentation User guide Token API Active naming Extensions Implementation Token implementation

Extension programming guide

Table of content
Foreword
Objective
Audience
Motivation
Applications
Shared computers
Control computers
Example
Implementation
Principle
Documentation
Packaging and testing
Programming
Public class

Foreword

Objective

In this document we explain how to develop a PageBox extension.

Audience

Java programmers.

Motivation

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:

  1. 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).

  2. 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:

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 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:


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





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:


Packaging and testing




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:




<extension>
	<ext-name>serial</ext-name>
	<ext-class>serialExt.Serial</ext-class>
</extension>




Notes:


  1. 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.
    2. 

  2. 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.
    3. 

  3. 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.
    4. 




    Contact:support@pagebox.net
©2002-2004 Alexis Grandemange. 
    Last modified
    .