This document describes how to use the PageBox API to:

1. Write on the PageBox log

2. Use the PageBox JDBC connection pool

3. Use resources available on the hosting Application server

4. Get the URLs of the other instances of the application deployed from the same Repository

Archive developers.

The PageBox API is implemented in a PageBoxAPI class of the PageBoxLib package:

The PageBox API implements sixteen methods, a constructor and the relConnections, getLog, getConnection, getResource, getExtension, getClones, registerCallback, unregisterCallback, getCandidate, addEntry, removeEntry and clearEntries methods. The registerCallback and unregisterCallback methods are described in the token API user guide. The ActiveNamingLogon, ActiveNamingLogoff, getEntries, getCandidate, addEntry, removeEntry and clearEntries methods are described in the Active Naming user guide.

The PageBoxAPI constructor has a parameter archDir, which is the directory where the archive was installed by PageBox. This directory is target_dir/archive_name_without_extension where target_dir is the value of the target element in the PageBox rules.xml and archive_name_without_extension is the archive name without its extension (typically .jar or .war.)

In case of error PageBoxAPI throws a PrivilegedActionException. To get the initial exception you can call PrivilegedActionException.getCause().

relConnections closes all open connections of the PageBox API connection pool and forbids the creation of new connections. You typically call relConnections in the destroy method of the Web application servlets, which is called when the Web application is unloaded.

relConnection exists in two forms:

1. A static method that takes the archive directory as parameter

2. A method without parameter

Note:

You cannot call relConnections (even in its static form) in the uninstall method of the installation class because the Web application and the installation class are loaded by different class loaders.

getLog returns a LogIF object. The LogIF interface is defined like this:

The info, warn and error methods allow writing messages on the log in a format

[ INFO | WARN | ERROR ] timestamp message_in_parameter

Use info for information messages, warn for warning and error for error messages.

The archive should write messages in a format Archive_name Class_name.Method_name diagnosis.

getConnection is the PageBoxAPI method that gives access to the PageBox JDBC connection pool.

The JDBC driver, URL and properties are defined in rules.xml by the PageBox administrator. See the installation guide for more information.

getConnection returns an object that implements the java.sql.Connection interface.

When it no longer needs the conn Connection the application should call the Connection.close method. The close doesn’t actually close the connection but make it available for other requestors.

If the connection pool is not defined getConnection returns null.

Here is an example:

getResource is the PageBoxAPI method that gives access to the resources available on the hosting Application server. A resource is identified by a name, for instance "jdbc" or "mail". PageBox administrators that define resources in rules.xml and archive programmers must agree on common conventions.

If the PageBox administrator declares a JDBC resource it should call it jdbc and use if possible a javax.sql.DataSource type and a Container auth.

If the PageBox administrator declares a JavaMail resource it should call it mail and use if possible a javax.mail.Session type and a Container auth.

If the PageBox administrator declares other resources (for instance Bean resources) it should document their name, type and use on its Web site.

The archive should always check

1. If the resource is defined

2. The type of the resource

If the resource is not allowed or not defined in the PageBox configuration getResource returns null.

Here is an example of use:

getExtension has three parameters:

• The name given to the extension in the PageBox configuration

• The class name of the parameter of the extension constructor. The PageBox API uses reflection to select the right constructor. If the class name is null the PageBox API creates the extension with a constructor without parameter.

• The parameter of the extension constructor. The PageBox API uses reflection to call the constructor with this parameter.

getExtension returns an instance of an extension class or null if:

• The extension is not defined in the PageBox configuration

• The permission to use this extension is not granted to the archive

• The extension class doesn’t have a constructor with this parameter type

The returned class implements the ExtensionIF interface:

Here is an example of use:

The PageBox administrator must document (typically on her or his Web site) the extensions that the PageBox supports:

• The extension names and for each extension

• The supported constructors

• The supported parameter types

getClones returns the URLs of the other instances of the archives deployed from the same Repository.

Let’s take the example of a Web archive that implements a JAX-RPC Web service with an interface MyServiceIF. The relative path of this Web service is jaxrpc/MyServiceIF. The Web archive includes the stub code allowing calling the Web service. The stub is called MyService_Impl. Then the Web archive will be able to invoke the myMethod method of the Web service of its clones with the following snippet:

The actual Web service URL is made of the URL returned in the clones array and of the relative URL known by the archive.

Note:

getClones can take time to complete. It actually calls all PageBoxes that have subscribed to the archive to make sure all hosting Application servers are running. In cases where the archive extensively calls its clones we recommend caching the clones array.

getControllingPageBoxURL returns the URL of the DeployIF Web service of the controlling PageBox.

getControllingPageBoxURL returns null if the PageBox administrator never went on the update page of the controlling PageBox.

getResourceUsage returns a ResourceUsage instance or null in case of error. ResourceUsage is defined like this:

MemUsage is defined like this:

Where:

• perUse is the percentage of CPU used

• perIdle is the percentage of CPU in idle mode = 100 – peruse

• perSystem is the percentage of CPU used in system mode

• perUser is the percentage of CPU used in user mode

• free is the amount of free memory in bytes. The default implementation uses RunTime.freeMemory and returns the amount of free memory in the Java Virtual Machine.

• total is the total amount of memory in bytes. The default implementation uses RunTime.totalMemory and returns the total amount of memory in the Java Virtual Machine.

• max is the maximum amount of memory that can be used in bytes. The default implementation uses RunTime.maxMemory and returns the maximum amount of memory that the Java virtual machine will attempt to use.

• netTime is the network service time in millisecond. The default implementation uses the time to send a frame to the next station on the ring (token API).

• msg is null when there were no problems in measurement collection. msg may contain a diagnosis in case of error or "first measure". In the later case CPU data are not valid.

All fields are not necessarily setup even when msg is null. Four fields should be set up:

• perUse

• perIdle

• free

• total

With the default implementation netTime is set up only when the token API or Active Naming is used.

Other fields are set up depending on the Operating System and Java Virtual Machine capabilities.

When a long field is not set up its value is -1. When a float field is not set up its value is Float.NEGATIVE_INFINITY.

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