User guide

In this document we assume that you have installed Java JDK 1.4 and either Java Web Services Developer pack (JWSDP) 1.3 / 1.5 or Tomcat 5 / 4.1 with Axis 1.1 and Xalan-Java 2.5 in a directory $TOMCAT_ROOT.

We also assume that you have inflated the corresponding version of pagebox.war in $TOMCAT_ROOT/PageBox and of repository.war in $TOMCAT_ROOT/Repository and that you have configured the PageBox and the Repository as described in java-download.html.

Subscriber

Subscriptions

The primary screen of the subscriber is subscribe.jsp.

Assuming that Tomcat is installed on your machine, is configured with SSL and listens on the 8443 port, you can display subscribe.jsp with https://localhost:8443/Repository/subscribe.

You first need to log with a subscriber user ID and password provided by the Repository administrator:

[This form depends on the browser.]

Then you should get this:

To subscribe a PageBox you must enter the URL of its DeployIF Web service. Copy the URL of its DeployIF Web service from the update page of this PageBox.

Assuming that Tomcat is installed on your machine, is configured with SSL and listens on the port 8443, you can display update with https://localhost:8443/PageBox/update.

Starting with version 0.0.7, PageBox access can and should be password protected. In this case you must log with a PageBox user ID and password provided by the PageBox administrator.

You should be displayed this:

Select the URL after "Subscription URL", copy and paste in the Subscribe text area. Then click on the Subscribe button to subscribe the target PageBox to your Repository.

Enter the PageBox user ID and password you used to display the update form in the PageBox user and PageBox password fields.

The Grade is not used in PageBox 0.1.1. You should set this field to a value that depends on the PageBox link speed. If the PageBox has a slow link (modem, frame relay) you can set it to 1 whereas if the PageBox has a fast link (OC 3) you can set it to 10.

Archive subscription

To subscribe to a selected list of archives the screen is asubscribe.jsp.

Assuming that Tomcat is installed on your machine, is configured with SSL and listens on the 8443 port, you can display asubscribe.jsp with https://localhost:8443/Repository/asubscribe.

You first need to log with a subscriber user ID and password provided by the Repository administrator.

To subscribe a PageBox you must enter the URL of its DeployIF Web service. Copy the URL of its DeployIF Web service from the update page of this PageBox.

Enter the PageBox user ID and password you used to display the update form in the PageBox user and PageBox password fields.

Then you should be displayed something like this:

Then you can click on Archives to display aselect.jsp:

When you check an archive that was not checked

This archive is installed on the subscribed PageBox
When this archive is updated updates are automatically installed on the subscribed PageBox

When you uncheck an archive that was checked this archive is uninstalled from the subscribed PageBox.

Installations and uninstallations take place when you click on the Refresh button.

Checking

The subscriber can check the archives installed on the PageBoxes that she or he subscribed and the PageBox administrator can check the archives installed on her or his PageBox with update:

Each archive is described by:

Its archive name
Its state, "installed", "setting pb" or "archive pb". In "setting pb" state the archive was deployed but the installation failed because the archive installation required features not supported by the PageBox. The subscriber may choose to unsubscribe this archive or to configure the missing features. In the latter case once it has updated the PageBox setting the subscriber may click on the Retry button to retry the installation of the archives in "setting pb" state. In "archive pb" state there is something wrong in the archive implementation. The subscriber may only report the problem to the publisher who has to publish a new version of the archive.
The URL of the Repository that deployed this archive
The ID of the Publisher who published this archive on the Repository
The archive size
The URL of this archive documentation

The subscriber and the PageBox administrator can also check the installation log (Audit link on the update form):

The form contains three buttons:

Clear: clears the log
Refresh: refresh the log display with the most recent entries
Log only errors/Log all. In "Log only errors" only errors and warning messages are logged

Each log entry contains three fields:

The entry type, ERROR, WARN or INFO. An ERROR entry is displayed on a red background whereas a WARN entry is displayed on a yellow background
The source, which can be the archive name or PageBox (internal processing)
The time when the log entry was recorded
The entry message

The subscriber can check the state of the PageBoxes that she or he subscribed with subscribe.jsp:

Each subscribed PageBox is described by a row that contains:

Two buttons to unsubscribe and force-unsubscribe the PageBox
A button to synchronize the archives installed on the PageBox with the list of the published archives
The URL of the PageBox
For each archive deployed on the PageBox the archive name and status (installed, error, pending, pending remove, maybe)

Force-unsubscribe removes the subscriber from the Repository even if the PageBox failed to answer the undeployment requests from the Repository: use the Force button when the PageBox no longer exist.

If the target PageBox installed the archive the archive status is installed.

If the target PageBox failed to install the archive because of an archive error the archive status is archive err. If the target PageBox failed to install the archive because of a setting problem of the target PageBox the archive status is PageBox err. In both cases look at the PageBox log for ERROR and WARN messages.

If the Repository failed to connect on the target PageBox for a deployment the archive status is pending. The Repository periodically retries the deployment.

If the Repository failed to connect on the target PageBox for an undeployment the archive status is "pending remove". The Repository periodically retries the undeployment.

If the Repository failed to deploy the archive on the target PageBox the archive is not added to the list of the archives of this subscribed PageBox. The cause may be a security problem (the subscriber, the Repository or the publisher is not allowed by the PageBox) or a problem in the configuration of the PageBox. If the problem is fixed the subscriber can click on the Sync button to retry the installation of the archives defined on the Repository but not installed on the PageBox.

When the Repository uses Relayed deployment it sets the archive status to maybe up to the time it receives a notification from the Relay PageBox. If the Repository doesn’t receive this notification on time it retries the deployment.

Therefore maybe is a transient state. pending should also be a transient state. If a PageBox remains in pending state one day or more it maybe doesn’t exist anymore and the subscriber may force-unsubscribe this PageBox. See the Repository documentation for more information.

In case of archive subscription the subscriber uses asubscribe.jsp to check the state of the PageBoxes that she or he subscribed:

The explanation is the same as for subscriptions.

Publisher

Publication

The primary screen of the publisher is publish.jsp.

Assuming that Tomcat is installed on your machine, is configured with SSL and listens on the 8443 port, you can display publish.jsp with https://localhost:8443/Repository/publish.

You first need to log with a publisher user ID and password provided by the Repository administrator.

To publish an archive:

Click on the Browse button. You should be displayed a "File Upload" form that allows you to select a jar archive on your local disks.
Set the documentation URL: this URL is sent to the target PageBoxes and displayed on the update form. This URL is the simplest way to provide information about the archive use.
Very important! If you need to dynamically install the archive on the target Application server (if the archive is a Web archive) check "Run application server installer".
Click on the Upload button.

Then the archive is deployed on the subscribed PageBoxes.

Checking

The publisher can list the archives that she or he has published with publish.jsp:

Each archive is represented by a row containing:

Two buttons, Delete (delete archive) and Force (force-delete)
The archive name
The date when this archive was published
The archive publisher
The URL of this archive documentation
The archive size

The publisher can delete or force-delete an archive.

In both cases the Repository uninstall the archive on all PageBoxes where the archive was installed.

To check the archive deployment and installation the publisher can click on the archive link. Then the publisher is displayed the list of the PageBoxes where the archive was installed:

For each PageBox are displayed the URL of the PageBox Web service and the deployment status. The publisher can click on the URL link to be displayed this kind of log:

Notes:

The displayed log only contains records related to this archive deployment: the publisher cannot see the PageBox records or the records of another archive.
The PageBox is normally password-protected and the Publisher normally doesn’t know the PageBox password. Behind the curtain the Repository queries the PageBox Web service using the password provided by the PageBox subscriber.
When the deployment failed for an archive-related reason the publisher should use the Delete button to uninstall/undeploy the archive, fix the archive problem and upload the new version.
In case of force-delete the archive is removed from the Repository subscribers even if the archive undeployment failed. See the Repository documentation for more information.

Repository administrator

A subscriber only sees the PageBoxes subscribed with her or his subscriber account.

A publisher only sees the archives published with her or his publisher account.

A Repository administrator uses an admin account. With this account:

subscribe.jsp and asubscribe.jsp display all PageBoxes subscribed on this Repository
publish.jsp displays all archives published on this Repository

For instance here is what a Repository administrator sees for a Repository with two subscribers, subscriber and subscriber2:

The Repository administrator can also display the Repository log (Audit link):

The form contains three buttons:

Clear: clears the log
Refresh: refresh the log display with the most recent entries
Log only errors/Log all. In "Log only errors" only errors and warning messages are logged

Each log entry contains five fields:

The entry type, ERROR, WARN or INFO. An ERROR entry is displayed on a red background whereas a WARN entry is displayed on a yellow background
The time when the log entry was recorded
The ID of the user that triggered the log writing. In case of retry no user triggered the log writing. In this case the Requestor field contains Retry.
The host from where the user made its request. In case of retry the Host field contains localhost. In case of Web service the Host field contains the Web service name.
The entry message