Java PageBox 
 New PageBox 
 Other products 

Installation API


The current installation process relies on configuration files.

The PageBox administrator typically defines that archives with a zip extension must be inflated in a directory named like the archive (but without extension) under the PageBox directory.

Furthermore to retrieve their controlling PageBox the Web applications have no choice but to assume that the PageBox URL is the beginning of the Web application URL.

This mechanism has many drawbacks:

Deploying an archive is a simple process:

  1. The publisher builds and uploads the archive onto the Repository

  2. The Repository deploys the archive on subscribing PageBoxes

  3. The PageBox deflates the installation

This process has also drawbacks for large-scale deployments:


We define two roles, subscriber and publisher and three functions

  1. The publisher describes the installation process.

  2. The subscriber defines where the published archive or file must be installed.

  3. The subscriber also defines security rules. Using the credential of the Publisher and of the Repository the subscriber can reject or accept the installation process proposed by the publisher.

Installation location

PageBox supports two types of subscriptions:

  1. Repository subscriptions. The subscriber says that it wants to get all archives and files published on a Repository. The subscribers will also get archives and files published after the subscription and the updates

  2. Archive subscriptions. The subscriber says that it wants to get an archive or file published on a Repository. The subscriber also wants to get the updates of this archive or file.

For the first subscription type the subscriber must define Repository-wide locations.

For the second subscription type, the subscriber defines at subscription time where the archive or file should be installed.

Though the installation process is flexible, we expect to see three kinds of installation:

Installation process

The publisher doesn’t need to specify an installation process.

By default the PageBox writes the file or inflates the archive at the location specified by the subscriber.

The publisher can package its delivery in an archive that contains an Install class. The following rules apply:

If security rules allow this operation the PageBox instantiates the class and calls its Process method.

Process is defined in the PageBoxInstall.Inst interface and has a prototype:

void Process(String location);

Where location is the installation location.

Security rules

A subscriber can subscribe to many repositories and get archives and files from many publishers.

The subscriber defines an XML file like this:




<repository>URL of the repository</repository>









<publisher>URL of the subscriber documentation</publisher>








Details are subject to change but the principle should remain the same.

For each Repository identified by its URL, the PageBox administrator defines a set of privileges such as the capability to instantiate and call an Install class. It is also possible to define default privileges for unlisted Repositories within an other element.

For each Publisher identified by its documentation URL, the PageBox administrator defines a set of privileges such as the capability to instantiate and call an Install class. It is also possible to define default privileges for unlisted Publishers within an other element.

Delta deployment

After a deployment:

  1. The subscribing PageBox keeps the deployed archive or file

  2. The Repository keeps the archive or file version that has been deployed

  3. The Repository knows which version is deployed on each subscribing PageBox

Therefore when the author publishes a new version the Repository can send to each subscribing PageBox the delta between the version installed on this PageBox and the new version.

We consider three cases:

We plan to use two delta algorithms:


VCDIFF is a Generic Differencing and Compression Data Format described by the RFC 3284. VCDIFF can be used either to compress data with a compression ratio close to gzip or to send only the delta between two versions. VCDIFF is CPU intensive. Therefore we plan to use the C compiled version.

For PageBox for Java we will wrap the VCDIFF library in a JNI shared library or dll.

For PageBox for .NET we will package the VCDIFF library in an ATL COM dll and we will create a .NET wrapper with tlbimp.

For PageBox for PHP we can write a PHP extension.


JARDiff format describes how to apply incremental updates to a JAR file.

JARDiff is specified by the JSR 56 (Java Network Launching Protocol and API, JNLP) that you can download from

A JARDiff is itself a jar file and contains complete copies of each new or changed file. It does not provide a way to incrementally update individual files within a JAR file. Therefore its compression ratio is lower than VCDIFF compression ratio. On the other hand it uses less resources. Beside adding or replacing its file members in the old version of the jar file JARDiff applies commands listed in an index file, which can be move or remove.


JARDiff will be supported only in PageBox for Java.

File deployment

When the file has a size below a value (typically 1500 bytes) it is deployed without differencing and compression.

Otherwise we use VCDIFF to compress if it is the first version published on the Repository or to generate a delta between the new version and existing versions. Then the Repository deploys the generated file. The target PageBox uses VCDIFF to either uncompress the file or apply the delta to the existing version.

jar deployment

This section also applies to ear and war files. These archives are used in their archived form by the target application.

If the jar file is the first version published on the Repository, the Repository deploys the jar file and the target PageBox writes the jar file on its target location.

Otherwise the Repository deploys the JARDiff between the new version and the deployed version. Then the target PageBox applies the JARDiff to the installed jar file.

Archive deployment

To be effective VCDIFF must used with uncompressed data whereas uploaded archives are usually compressed.

We considered a first solution:

  1. Inflate the archive on a temporary directory

  2. Tar the temporary directory

  3. VCDIFF with the tar file of the previous version

We consider now a solution that uses fewer resources:

  1. Sends the archive in its uploaded format if it is the first version

  2. Otherwise enumerate the archive files

  3. If the file is in the previous version do nothing

  4. If the file is a jar file apply the jar deployment algorithm and add the file to a target tar

  5. Otherwise apply the file deployment algorithm and add the file to the target tar

  6. If the file existed in the previous version but not in the new version add a "remove" entry to an index file

  7. Once all files have been enumerated, add the index to the target tar and send the target tar

We plan to support the following archive formats:


The Installation API is implemented in an Api class defined in the PageBoxInstall package.

The Api class implements a getControlPageBox method with a prototype:

String getControlPageBox();

getControlPageBox returns null if the application has not be deployed with PageBox.

Otherwise getControlPageBox returns the URL of the controlling PageBox.

Reservation Controls Java controls
Polaris Grid Coordinator Grid V2
Distribution Installation NWS
2001-2004 Alexis Grandemange   Last modified