|Presentation||Install||User guide||Developer guide||Programming||Port||Repository||PageBox||Release notes|
In this document we explain how to package a Web application for PageBox deployment.
PageBox allows deploying whatever can be packaged in a jar archive:
In the simplest cases you have nothing to do: To deploy a file system directory create your archive with jar cf myarchive.jar. The same comment also applies to Web archives as far as you don’t need to perform a post installation – for instance to create a database table.
To install a product (a special case of file system directory deployment), to run a post-installation or update a database you need to implement an installation class. This class must:
This document describes the support of installation classes in PageBox and how to write an installation class.
Installation class support
The installation class is loaded, instantiated and called by the install and uninstall methods of DeployImpl.
These methods use an InstallClassLoader class loader to create and instantiate the installation class:
The installation class is called in three contexts. A parameter toUpdate indicates to the installation class in which context it is called.
In case of new installation the PageBox:
In case of update the PageBox:
Normally the version i + 1 replaces the version i and the update is a delta update. However if the PageBox is not available when the version i + 1 is deployed the PageBox will receive a full archive of version i + 1 or maybe i + n during a retry.
In case of uninstallation the PageBox:
An installation class must implement the PageBoxLib.InstallIF interface, which is defined like this:
archPath, pba and resources are set by the PageBox administrator. See the Installation guide for more information.
The install and uninstall can throw exceptions or return an error message.
PageBox interprets any kind of Exception or Error as an archive error.
PageBox interprets a non-null return String as an environment error (the PageBox administrator didn’t configure something, for instance a resource, that the method needs to run).
PageBoxAPI has the following signature:
The LogIF interface is defined like this:
error messages are displayed with a red background whereas warning messages are displayed with a yellow background. Information messages are recorded only when the tracing mode is set to info. All messages are displayed with a timestamp.
The resource Map contains ResourceInfo objects. The ResourceInfo class is defined like this:
The installation class can use the resource map to update the archive’s web.xml.
To make SQL requests the installation class can use the PageBoxAPI database:
The installation class can also use resource databases.
The PageBox must refer to resources used in the installation class. Its web.xml should contain resource references like this:
The getResource parameter ("jdbc" in the example above) is a symbolic name defined by the PageBox administrator. Application developers can assume for instance that all PageBoxes define a jdbc database resource whereas hosting Application servers can use different reference names.
For more information about the PageBox API check the API documentation.
The install class can only read, write or update files in archPath. The install class can also create directories but only under archPath. In the same way the install class can connect to the databases:
In the first case the databases are managed by the hosting Application server. All Web applications can access their data.
In the latter case the database is Web-application specific and typically created automatically just before the invocation of the Install class.
Use the resource databases for context data.
Using resource databases assumes that there is a contract between the PageBox administrator and the Web application developer. The developer expects that a database identified by a name xxxx contains a given set of tables defined with a given set of fields. The developer shouldn’t create or drop tables. The developer should update the tables in a way consistent with the other users of the databases, for instance using stored procedures.
Use the PageBoxAPI connections for Web application data.
Because the database is often created automatically just before the invocation of the Install class, the Install class should create and populate the needed tables.
In case of update the uninstall method of the old installation class is called with toUpdate = true and then the install method of the new installation class is called with toUpdate = true.
Due to possible failure of target PageBoxes we cannot guarantee that the new version is i + 1 when the old version is i. A version can be skipped.
In case of a Web archive the installation class can update the archive’s web.xml and other configuration files. We gave an example above where the installation class adds resources defined in the resource map to the archive’s web.xml.
Generic installation class
The generic installation class is a general-purpose installation class that creates and populates a set of tables with data stored in a set of comma-separated (.csv) files and updates the archive’s web.xml. The generic installation class uses the PageBoxAPI database connection pool (defined by rules.xml parameters).
Look at the euroLCC example for information regarding the implementation of the generic installation class.
Table creation and update
The generic installation class looks for files defined in the archPath/sqlinstall directory.
These files must be .csv files with the same number of fields on each line.
The first line must contain the names of the table columns.
The second line must contain the column definitions.
Every subsequent line must contain data defining the content of a table row.
Here is an example excerpt called route.csv:
The generic installation class creates a table for each .csv file with the same name as the .csv file without the extension. For the example above the generic installation class creates a route table with the following request:
Then for each remaining line in route.csv the generic installation class adds a row with a request like this:
Therefore you cannot define fields containing commas (,) and double quotes (").
The generic installation class replaces the first <!--Install_wordir--> in web.xml by archPath.