|Presentation||User guide||Token API||Active naming||Extensions||Implementation||Token implementation|
PageBox API user guide|
This document describes how to use the PageBox API to:
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:
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
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:
getExtension returns an instance of an extension class or null if:
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:
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.
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:
All fields are not necessarily setup even when msg is null. Four fields should be set up:
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.