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:

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

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:

• 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

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.

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:

• 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

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:

Where location is the installation location.

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

The subscriber defines an XML file like this:

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.

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:

• File deployment

• Archive deployment

• jar deployment

We plan to use two delta algorithms:

• VCDIFF for File and archive deployment

• JARDiff for jar deployment

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

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.

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.

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:

• Zip archives

• tar.gz and bzipped tar

• Maybe cab archives with the .NET version

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

The Api class implements a getControlPageBox method with a prototype:

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

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