Installation API

PageBox

Installation API

Table of content

Motivation
Roles
Installation location
Installation process
Security rules
Delta deployment
VCDIFF
jardiff
File deployment
jar deployment
Archive deployment
API

Motivation

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:

An archive is inflated in a PageBox subdirectory whereas for Control deployment we would need to install the code in the user application directory
It hardly allows doing more than archive inflation or file copy whereas each deployed archive or file can have specific post installation requirements. It means that in most cases only the update is fully automated. The first installation requires manual work.
The extension is not enough to decide what has to be done at installation
To inflate archives we run system commands, which means that PageBox must be allowed to run at least deflation commands. It is dangerous for a server on Internet.

Deploying an archive is a simple process:

The publisher builds and uploads the archive onto the Repository
The Repository deploys the archive on subscribing PageBoxes
The PageBox deflates the installation

This process has also drawbacks for large-scale deployments:

The deployment on 1000 subscribers requires 1000 times more time than a deployment on one subscriber. We describe how we solve that problem in the Grid V2 document.
In case of update we send again the whole archive or file whereas the changes from version -1 to the new version are generally small

Roles

We define two roles, subscriber and publisher and three functions

The publisher describes the installation process.
The subscriber defines where the published archive or file must be installed.
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:

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

File copy. In that case the location is the target directory
Archive inflation. In that case the location is the directory where the archive will be inflated
Database update. In that case the location is a connection string that depends on the PageBox flavor, an ADO connection string in case of PageBox for .NET and a JDBC connection string in case of PageBox for Java. In this case the subscriber must specify two locations, the target directory and the connection string

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:

The class file in Java must be called Install.class
The class dll in .NET must be called Install.dll
It must contain an Install class that implements the PageBoxInstall.Inst interface.

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:

<rules>

<rule>

<repository>URL of the repository</repository>

<allow>install</allow>

</rule>

<other>

<allow>Install</allow>

</other>

</repositories>

<rule>

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

<allow>Install</allow>

</rule>

<other>

</other>

</publishers>

</rules>

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:

The subscribing PageBox keeps the deployed archive or file
The Repository keeps the archive or file version that has been deployed
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:

File deployment
Archive deployment
jar deployment

We plan to use two delta algorithms:

VCDIFF for File and archive deployment
JARDiff for jar deployment

VCDIFF

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

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 http://java.sun.com/products/javawebstart/download-spec.html.

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.

Note:

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:

Inflate the archive on a temporary directory
Tar the temporary directory
VCDIFF with the tar file of the previous version

We consider now a solution that uses fewer resources:

Sends the archive in its uploaded format if it is the first version
Otherwise enumerate the archive files
If the file is in the previous version do nothing
If the file is a jar file apply the jar deployment algorithm and add the file to a target tar
Otherwise apply the file deployment algorithm and add the file to the target tar
If the file existed in the previous version but not in the new version add a "remove" entry to an index file
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:

Zip archives
tar.gz and bzipped tar
Maybe cab archives with the .NET version

API

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.

Java PHP .NET
Reservation Controls Java controls
Polaris Grid Coordinator Grid V2
Distribution Installation NWS