| Support | Home | Word |
|
|
PageBox |
|
|
|
|
|
|
| Presentation | User guide | Token API | Active naming | Extensions | Implementation | Token implementation |
PageBox API user guide
| Table of content | |
|
This document describes how to use the PageBox API to:
Write on the PageBox log
Use the PageBox JDBC connection pool
Use resources available on the hosting Application server
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:
class PageBoxAPI { static void relConnections(String archDir) { ... } PageBoxAPI(String archDir) throws PrivilegedActionException { ... } void relConnections() { ... } LogIF getLog() { ... } java.sql.Connection getConnection() { ... } ResourceInfo getResource(String name) { ... } ExtensionIF getExtension(String name, String parmClass, Object parm) { ... } String[] getClones() { ... } boolean registerCallback(TokenCallbackIF tci) { ... } boolean unregisterCallback() { ... } String getControllingPageBoxURL() { ... } void ActiveNamingLogon() { ... } void ActiveNamingLogoff() { ... } String[] getEntries() { ... } String getCandidate(String name, Serializable must, ActiveComparable niceif) { ... } void addEntry(String name, Serializable must, ActiveComparable niceif, String url) { ... } void removeEntry(String name) { ... } void clearEntries() { ... } ResourceUsage getResourceUsage() { ... } } |
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:
A static method that takes the archive directory as parameter
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:
interface LogIF { void info(String msg); void warn(String msg); void error(String msg); } |
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:
PageBoxAPI API = new PageBoxAPI(archPath); Connection conn = API.getConnection(); Statement stmt = conn.createStatement(); ResultSet rs = stmt.executeQuery("SELECT id, name, price, qty FROM article"); ... conn.close(); |
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 defined
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:
PageBoxAPI api = new PageBoxAPI(dir); ResourceInfo ri = api.getResource("jdbc"); if ((ri != null) && (ri.type.equals("javax.sql.DataSource"))) { Context initCtx = new InitialContext(); Context envCtx = (Context) initCtx.lookup("java:comp/env"); DataSource ds = (DataSource)envCtx.lookup(ri.reference); Connection conn = ds.getConnection(); // Use the resource connection ... conn.close(); } |
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:
interface ExtensionIF { Object call(Object obj) throws Exception; } |
Here is an example of use:
PageBoxAPI inst = new PageBoxAPI(workDir); ExtensionIF ei = inst.getExtension("myextension", "java.lang.String", "constructor string"); ... ArrayList resp = (ArrayList)ei.call("myparam"); |
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:
PageBoxAPI api = new PageBoxAPI(dir); String[] clones = api.getClones(); if (clones == null) { // No clone available } MyServiceIF msi = MyService_Impl.getMyServiceIFPort(); Stub s = (Stub)msi; for (int i = 0; i < clones.length; ++ i) { s._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, clones[i] + "/jaxrpc/MyServiceIF"); msi.myMethod(...); } |
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:
class ResourceUsage extends MemUsage { float perUse; float perIdle; float perSystem; float perUser; } |
MemUsage is defined like this:
class MemUsage implements Serializable { long free; long total; long max; long netTime; String msg; } |
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
.