Developer guide

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:

Be called Install.class
Implement a PageBox.InstallIF interface
Be stored in WEB-INF/classes or at the root of the archive

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:

InstallClassLoader icl = new InstallClassLoader(archPath2);

Class inst = icl.loadClass("Install");

InstallIF ii = (InstallIF)inst.newInstance();

The installation class is called in three contexts. A parameter toUpdate indicates to the installation class in which context it is called.

New installation

In case of new installation the PageBox:

Inflates the archive
Calls the install method of the installation class with toUpdate = false
Deploys the archive on the Application server if it is a Web archive

Update

In case of update the PageBox:

Calls the uninstall method of the old version of the installation class with toUpdate = true
Inflates the new version of the archive or applies the jardiff changes in case of delta update
Calls the install method of the new version of the installation class with toUpdate = true
Reloads the archive on the Application server if it is a Web archive

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.

Uninstallation

In case of uninstallation the PageBox:

Removes the archive from the Application server if it is a Web archive
Calls the uninstall method of the installation class with toUpdate = false
Removes the archive from the PageBox host file system

Development

InstallIF

An installation class must implement the PageBoxLib.InstallIF interface, which is defined like this:

interface InstallIF {

String install(String archPath, PageBoxAPI pba, Map resources, boolean toUpdate) throws Exception;

String uninstall(String archPath, PageBoxAPI pba, Map resources, boolean toUpdate) throws Exception;

}

Where:

archPath is the path where the archive was inflated
pba is a PageBoxAPI object
resources describes the resources available on the target Application server
toUpdate equals true when the archive was already installed in case of install or the archive will be reinstalled in case of uninstall (re-installation)

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:

class PageBoxAPI {

LogIF getLog();

java.sql.Connection getConnection();

ResourceInfo getResource(String name);

String[] getClones();

}

Where

getLog returns an interface to a logging object allowing writing on the PageBox log
getResource returns data about a named resource
getClones returns the URLs of the other instances of the Web archive installed from the same Repository
getConnection returns an SQL connection from a PageBox connection pool

The LogIF interface is defined like this:

public interface LogIF {

public void info(String msg);

public void warn(String msg);

public void error(String msg);

}

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:

class ResourceInfo {

String reference;

String type;

String auth;

}

Where:

reference is the JNDI name of the resource.
type is the interface implemented by the resource.
auth relates to authorization. auth indicates whether the application component code performs resource signon programmatically or whether the container signs onto the resource based on the principle mapping information supplied by the deployer. See the Servlet specification for more information.

The installation class can use the resource map to update the archive’s web.xml.

Iterator i = resources.values().iterator();

while(i.hasNext()) {

ResourceInfo ri = (ResourceInfo)i.next();

pw.println("<resource-ref>");

pw.println("<res-ref-name>" + ri.reference + "</res-ref-name>");

pw.println("<res-type>" + ri.type + "</res-type>");

pw.println("<res-auth>" + ri.auth + "</res-auth>");

pw.println("</resource-ref>");

}

To make SQL requests the installation class can use the PageBoxAPI database:

Connection conn = pba.getConnection();

Statement stmt = conn.createStatement();

...

conn.close();

The installation class can also use resource databases.

ResourceInfo ri = pba.getResource("jdbc");

Context initCtx = new InitialContext();

Context envCtx = (Context)initCtx.lookup("java:comp/env");

DataSource ds = (DataSource)envCtx.lookup(ri.reference);

Connection conn = ds.getConnection();

Statement stmt = conn.createStatement();

...

conn.close();

Note:

The PageBox must refer to resources used in the installation class. Its web.xml should contain resource references like this:

<resource-ref>

<res-ref-name>jdbc/pageboxa</res-ref-name>

<res-type>javax.sql.DataSource</res-type>

<res-auth>Container</res-auth>

</resource-ref>

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.

Guidelines

Security

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:

Described by resources or
Whose connections are returned by PageBoxAPI.getConnection.

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.

Databases

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.

Update

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.

Therefore

uninstall(true) doesn’t necessarily need to do something
install(true) should check the old version number

Web archive

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:

origin,destination,url

char(3) not null,char(3) not null,varchar(128) not null

AMS,BCN,http://www.easyjet.com/

AMS,BFS,http://www.easyjet.com/

...

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:

CREATE TABLE route (origin char(3) not null, destination char(3) not null, url varchar(128) not null)

Then for each remaining line in route.csv the generic installation class adds a row with a request like this:

INSERT INTO route (origin, destination, url) values("AMS", "BCN", "http://www.easyjet.com/")

Note:

Therefore you cannot define fields containing commas (,) and double quotes (").

web.xml update

The generic installation class replaces the first  in web.xml by archPath.