This document explains how to use the Epimetheus Web archive and presents the Epimetheus implementation.

In this document we assume that you have installed:

• Java JDK 1.4

• Java Web Services Developer pack (WSDP) 1.2, which includes Tomcat 5

• PageBox for Java version 0.0.9ter or above

• MySql. Pandora was tested with version MySql 3.23.53. It should be easy to adapt to other databases.

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:

1. To setup a database resource in Tomcat

2. To create a SQL database and a table in this database

3. To setup a serial extension

4. To setup a PageBox

5. To subscribe the PageBox to the Repository

6. To publish the Epimetheus archive on a Repository

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:

Notes:

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:

• The Communication API documentation and especially the PlatformSpecific.html page

• The http://web.haystack.mit.edu/SRT/linuxdl.html page. SRT stands for Small Radio Telescope, which shows how wide are the applications of the Communication API.

We suggest this setting:

1. Copy commapi_root/commapi/javax.comm.properties into jdk_root/lib

2. Copy commapi_root/commapi/comm.jar into jwsdp_root/shared/lib (same directory as the PageBoxAPI archive)

3. If you run Windows add commapi_root\commapi to the PATH used to start the Application server

4. If you run Solaris add commapi_root/commapi to the LD_LIBRARY_PATH used to start the Application server

5. If you run another Operating System you might to compile an RXTX shared library according to the RXTX instructions. Then add this shared library to the shared library path (LD_LIBRARY_PATH on Linux).

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:

1. Go on the subscribe form of the Repository

2. Logon with the subscriber account defined in the PageBox’s rules.xml

3. Enter the URL of the PageBox’s deploy Web service, the user ID and password of your PageBox and click on the subscribe button

To publish Epimetheus on the Repository:

1. Go on the publish page of the Repository and log on with a Publisher account

2. Click on the Browse button and select the paydeliver.war archive. Then enter the documentation URL if you want and check the "Run application server installer" checkbox.

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.

1. Model View Controller (MVC) architecture where ContactCtrl.java acts as the controller, contact.jsp acts as the view and ContactBean acts as the model.

2. Data stored in a RDBMS and accessed using JDBC

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:

Note:

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:

• The servlet’s init method that sets some variables

• The servlet’s doGet and doPost methods that process the user requests and call the initialize and the populate method

• initialize that gets a DataSource from the resource

• populate that uses this DataSource to read the contact table and populate the ContactBean’s contacts TreeMap

We detail below the methods of interest.

initialize

1. Creates a PageBoxAPI object

2. Calls its getResource method to query a resource whose symbolic name is jdbc

3. Uses JNDI to call the DataSourceFactory and get a DataSource object

populate

1. Gets a Connection from the DataSource

2. Reads the contact table with this Connection

3. Populates the contacts TreeMap of ContactBean

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:

• The servlet’s init method that sets some variables

• The servlet’s doGet method that calls the initialize method and the extension.

• initialize that instantiates the extension

SerialCtrl is fairly simple. Only doGet is of interest.

doGet:

1. Calls the initialize method to get a PageBoxAPI instance and to use this instance to get an extension instance

2. Calls the call method of the extension instance to get the list of the host’s ports

3. Set the ports member of the SerialBean instance to this list

4. Set the SerialBean instance as a request attribute

5. Forwards the request to serial.jsp

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.

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