This document explains how to use the Epimetheus Web archive and presents the Epimetheus implementation.
In this document we assume that you have installed:
See the PageBox installation guide for more information about the PageBox installation.
Epimetheus is an example that illustrates the use of resources and extensions in PageBox.
To test Epimetheus you need:
To test Epimetheus with a local MySql database add this snippet in the Engine or in the Host element of $WSDP_ROOT/conf/server.xml:
We add a resource named jdbc/pageboxa.
This resource defines a connection pool with at most four active connections.
This connection pool will connect to the database identified by jdbc:mysql://localhost/pageboxa using the com.mysql.jdbc.Driver driver. It will use the pageboxa account whose password is pagebox.
In the JDBC URL, jdbc:mysql://localhost/pageboxa, pageboxa represents the database name.
You can change this name as well as the MySql account/password.
To create the pageboxa database use the mysql command and enter:
Then to create the Epimetheus table, called contact enter under mysql prompt:
You can check that the table is properly setup with desc contact. You should get this response:
MySql can be tricky.
For instance on Unix MySql listens both on Unix socket and on port 3306.
When you use the mysql command mysql uses the Unix socket whereas the com.mysql.jdbc.Driver uses the TCP port.
You can force the mysql command to use the TCP port and simulate Application server requests with:
Account management is not trouble-free either. We suggest to set up mysql in secure mode (authentication required) with these commands:
The first command creates a pageboxa account. The second command set a password to the root account (much needed on Internet, 3306 is the well-known mysql port) and the last command forbids the access to MySql resources to non-authenticated users.
The extension uses the Sun’s Java Communication API that you can download from http://java.sun.com/products/javacomm/. The Communication API is made of a Java archive, comm..jar and of a shared library (.so or .dll) and supports RS 232 serial ports and IEEE 1284 parallel ports. Sun provides the Solaris and Windows 32 shared libraries. Kevin Hester has written a portable shared library, RXTX, for Linux and Unix that has been successfully ported on a large number of platforms. Therefore if you run a Windows OS download the Windows version, if you run Solaris download the Solaris version else download the Solaris version 2 to get the Java code and RXTX to get the shared library. Select the RXTX archive that supports javax.comm.
There are two excellent sources of information about the Communication API setting:
We suggest this setting:
Copy serial.jar into jwsdp_root/shared/lib (same directory as the PageBoxAPI and the Communication API archives).
You must configure a JDBC resource in your PageBox’s rules.xml.
Then you can subscribe your PageBox to a Repository where Epimetheus is or will be published.
Next you publish Epimetheus. See the PageBox user’s guide for more information. Note that you can publish Epimetheus either before or after subscribing the PageBox.
You can use this rules.xml file:
The PageBox will accept deployment request from Repositories where this PageBox was subscribed with the subscriber account. This PageBox will only install archives published with the publisher account but it will also inflate the archives from other publishers when the Repository is http://localhost:8080/Repository/jaxrpc/RepoQueryIF.
This PageBox will inflate the deployed archives in E:\java\PageBoxA\archive_name. Web archives will be deployed on the Tomcat_URL/PageBoxA/archive_name.
This PageBox defines a resource whose symbolic name is jdbc. The reference name, the type and the auth of this resource must be the same as defined on the Resource line in $WSDP_ROOT/conf/server.xml. Only archives published by publisher can use this resource.
This PageBox also defines a extension whose symbolic name is serial. The extension class name, serialExt.Serial must be the name of a public class defined in the serial.jar extension. Only archives published by publisher can use this extension.
You probably have to change parameters such as the Repository name or the target name.
To subscribe your PageBox to the Repository follow the following steps:
To publish Epimetheus on the Repository:
Start your browser. Assuming that you set rules.xml as described above you can display the contact form of Epimetheus for a WSDP running locally on default port (8080) with http://localhost:8080/PageBoxA/epimetheus/contact. You should get something like:
To add a new contact record enter her name, phone number and optionally her fax number, e-mail address, zip code and address and click on the add button. To remove a contact record enter her phone number and click on the delete button.
To test the extension, click on the serial extension link. You should get something like this:
In this case the host (a PC running Windows XP) has two serial ports (COM1 and COM3) and two parallel ports (LPT1 and LPT2). These ports are not owned, which means that a more sophisticated extension could acquire these ports to drive a device.
Epimetheus is made of the following components:
The installation class implements the PageBoxLib.InstallIF interface.
The implementation of the uninstall method is empty.
The implementation of the install method reads the Epimetheus’s web.xml and looks for two placeholders, <!--Install_wordir--> and <resource-ref>.
install replaces <!--Install_wordir--> by the directory of the inflated archive.
When it finds the <resource-ref> placeholder install replaces it with code generated from the resource Map:
With the rules.xml above install generates:
The <resource-ref> placeholder is not well formed XML. If case of install failure the Epimetheus Web archive won’t be deployed on the Application server.
ContactCtrl implements five methods:
We detail below the methods of interest.
doPost handles user requests.
If the user clicked on the add button doPost uses the query parameters to build an INSERT INTO CONTACT SQL request. doPost gets a Connection from the DataSource and uses this Connection to insert a new record in the contact table.
If the user clicked on the delete button doPost uses the query parameters to build a DELETE FROM CONTACT SQL request. doPost gets a Connection from the DataSource and uses this Connection to remove a record from the contact table.
ContactBean has a single method, getContacts that enumerates the content of the contacts TreeMap and formats this content in HTML.
To display the contacts sorted by name and phone number, contacts entries have a ContactKey key made of the contact name and phone number. ContactKey implements the Comparable interface in order to sort contact per ascending name and when names are equal per ascending phone number.
The extension public (and unique) class is called Serial.
Because it is an extension Serial implements the ExtensionIF interface and therefore the call method.
The call method calls CommPortIdentifier.getPortIdentifiers from the Java Communication API to get an enumeration of the host’s ports. Then call returns an ArrayList whose entries are string containing the name of the port, the application that currently uses the port and the type of the port (SERIAL or PARALLEL).
SerialCtrl implements three methods:
SerialCtrl is fairly simple. Only doGet is of interest.
serial.jsp retrieves the SerialBean object from the request attribute and calls its getPorts method to display the ports.
SerialBean implements the getPorts method.
getPorts formats the ports list set by SerialCtrl in HTML and returns this formatted string to serial.jsp.