PageBox for Java: Web application deployment using Java PageBox

for
 PageBox for Java 
 API 
 Demo 
 Background 
Presentation Download User guide Implementation Epimetheus euroLCC Prometheus

Pandora user guide

Objective

This document describes how to use the Pandora Web archives:

  • distributed.war: distributed Web archive with the end-user interface

  • central.war: central Web archive

  • paydeliver.war payment application and delivery application mockup

Assumptions

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.

PageBox preparation

You need to set up at least four PageBoxes to test the environment:

  1. At least one PageBox hosting distributed.war

  2. One PageBox hosting central.war

  3. One PageBox hosting paydeliver.war in a payment role

  4. One PageBox hosting paydeliver.war in a delivery role

You can run all these PageBox Web applications under the same Tomcat instance, which is meaningless in a production environment but useful for testing.

distributed.war PageBox

The distributed.war PageBox must be configured:

  1. To run the installation class of distributed.war

  2. With a JDBC connection

Here is an example of rules.xml configuration file:

<rules>

<subscriber>

<name>subscriber</name>

<password>subscriber</password>

</subscriber>

<publishers>

<publisher>

<name>publisher</name>

<allow>install</allow>

</publisher>

</publishers>

<repositories>

<repository>

<name>http://localhost:8080/Repository/jaxrpc/RepoQueryIF</name>

<allow>install</allow>

</repository>

<default>

<allow>none</allow>

</default>

</repositories>

<target>E:\java\PageBox1</target>

<root-path>/PageBox1</root-path>

<driver>com.mysql.jdbc.Driver</driver>

<url>jdbc:mysql://localhost/pandora</url>

</rules>

In this case if distributed.war was published by the publisher user or if distributed.war was deployed from the http://localhost:8080/Repository/jaxrpc/RepoQueryIF Repository then PageBox calls the installation class of distributed.war.

Pandora has been tested with the MySql database and the MySQL Connector/J 2 driver. Therefore the JDBC driver is com.mysql.jdbc.Driver and the url is jdbc:mysql://host/database.

You might need to install MySql and Connector/J and to create a database for the PageBox applications:

  1. Download MySql 3.23 from http://www.mysql.com/downloads/index.html

  2. Download Connector/J 2 from http://www.mysql.com/downloads/api-jdbc-stable.html

  3. Install MySql. Follow the installation instructions (that depend on the platform)

  4. Inflate the Connector/J archive

  5. Copy mysql-connector-java-2.0.14-bin.jar from the Connector/J directory in $WSDP/common/lib where $WSDP is the Java Web Services Developer pack (WSDP) directory

  6. To create a database for PageBox applications make sure mysqld is running, run the mysql command and once you get the mysql prompt enter CREATE DATABASE database

central.war PageBox

The central.war PageBox must be configured:

  1. To run the installation class of central.war

  2. With a JDBC connection

Therefore you can follow the same installation instructions as for the distributed.war PageBox.

paydeliver.war PageBox

The paydeliver.war PageBox doesn’t use JDBC. The paydeliver.war PageBox must only be configured to run the installation class of paydeliver.war. Here is the rules.xml we used for our tests:

<rules>

<subscriber>

<name>subscriber2</name>

<password>subscriber</password>

</subscriber>

<publishers>

<publisher>

<name>publisher</name>

<allow>install</allow>

</publisher>

</publishers>

<repositories>

<repository>

<name>http://localhost:8080/Repository/jaxrpc/RepoQueryIF</name>

<allow>install</allow>

</repository>

<default>

<allow>none</allow>

</default>

</repositories>

<target>E:\java\PageBoxSub2</target>

<root-path>/PageBoxSub2</root-path>

</rules>

Archive update

You may need to modify the distributed.war and the central.war Web archive.

The simplest solution is to

  1. Inflate the Web archive in a temporary directory with a command jar xvf archive

  2. Make the changes

  3. Rebuild the archive with jar cvf archive_path .

distributed.war

You might need to change central.txt and article.csv.

central.txt

central.txt contains the URL of the Update Web service of the central Web application. In the distributed.war delivery central.txt contains:

http://localhost:8080/PageBox2/central/jaxrpc/UpdateIF

Where:

  1. http://localhost:8080 is the Tomcat URL

  2. PageBox2 is the root-path defined in the rules.xml of the central.war PageBox

  3. central is the archive name

  4. jaxrpc/UpdateIF is the path of the Update Web service, defined in the central.war’s web.xml

article.csv

article.csv contains the data to load in the article table.

article.csv contains one line per article to insert. Each line must contain four columns separated by commas:

  1. article ID that must be an integer

  2. article name, a string

  3. article price that is parsed as a float: enter it in a format iii.jj

  4. article number that must be an integer

In the distributed.war delivery article.csv contains:

0,article1,999.5,1000

1,article2,1245.0,500

2,article3,1495.0,600

3,article4,1695.5,400

web.xml

The distributed Web application uses the following context parameters:

Name

Meaning

workdir

Directory where the Web application is installed. Automatically updated by the installation class. Don’t change the <!--Install_wordir--> placeholder.

period

Every period the distributed application sends the committed commands to the central application

check-readfile

Optional parameter. If check-readfile is not defined CheckSandbox doesn’t check the read access. Path of the file that CheckSandbox tries to read to assess the sandbox. check-readfile should be a text file (with line separators.)

check-writefile

Optional parameter. If check-writefile is not defined CheckSandbox doesn’t check the write access. Path of the file that CheckSandbox tries to write and delete to assess the sandbox. check-writefile shouldn’t exist.

check-command

Optional parameter. If check-command is not defined CheckSandbox doesn’t check if it can run commands. Path of the command that CheckSandbox tries to run to assess the sandbox. check-command should exist.

check-loadlib

Optional parameter. If check-loadlib is not defined CheckSandbox doesn’t check the capability to run native code. Name without extension of the native library that CheckSandbox tries to load to assess the sandbox. check-loadlib should exist and be on the PATH (Windows) or LD_LIBRARY_PATH (Unix, Linux) of Tomcat on startup. On Windows you can set check-loadlib to CheckLoad and use CheckLoad.dll.

check-class

Optional parameter. If check-class is not defined CheckSandbox doesn’t check the capability to run class loaders. CLASSPATH used by CheckClassLoader to assess the sandbox. check-class should exist and contain pandora/CheckLoaded.class.

You can comment all parameters starting with check if you don’t want to exercise the sandbox.

If you choose to exercise the sandbox you probably have to change check-readfile, check-writefile, check-command. You must provide a file to read and a command to execute and put the CheckLoad shared library and CheckLoaded class at the right locations.

central.war

You might need to change article.csv. The central.war’s article.csv is the same format as the distributed.war’s article.csv.

Note:

Each time the distributed application calls the Update Web service to upload queued commands the central application returns its article list. Therefore an interesting test consists of adding new articles to article.csv, rebuilding and republishing central.war. Only article.csv will actually be sent to the distributed application because in case of update the Repository only sends the jardiff. Then the distributed.war PageBox will rerun the installer that will repopulate the article table of the distributed application.

Publication

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

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.

Repeat the process for the central.war and the distributed.war archives.

Then you should see something like this:

Subscription

You must subscribe your PageBoxes to the Repository.

Follow the following steps:

  1. Go on the asubscribe (archive subscribe) form of the Repository

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

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

  4. For the PageBoxes that should host the paydeliver.war archive (delivery and payment servers), click on the archives link to display the aselect form and check the paydeliver.war row in the list

  5. For the PageBox that should host the central.war archive, click on the archives link to display the aselect forn and check the central.war row in the list

  6. For the PageBox(es) that should host the distributed.war archive, click on the archives link to display the aselect forn and check the distributed.war row in the list

Installation verification

If you configured properly the PageBoxes and your subscriptions, paydeliver.war, central.war and distributed.war should be properly installed.

You can check that the database tables were properly setup. For instance to check the Pandora database used by a distributed instance, run the mysql command.

mysql> use pandora

Database changed

mysql> show tables;

+-------------------+

| Tables_in_pandora |

+-------------------+

| article |

| command |

| item |

+-------------------+

You should find three tables, article, command and item. The article table should be already populated. With the article.csv file presented above you should get this:

mysql> select * from article;

+----+----------+--------+------+------+

| id | name | price | qty | sold |

+----+----------+--------+------+------+

| 0 | article1 | 999.5 | 1000 | 0 |

| 1 | article2 | 1245 | 500 | 0 |

| 2 | article3 | 1495 | 600 | 0 |

| 3 | article4 | 1695.5 | 400 | 0 |

+----+----------+--------+------+------+

4 rows in set (0.06 sec)

Now you can use the Pandora applications.

Referrer site

The installed distributed application contains a referrer part made of:

  • login.jsp

  • link.jsp

  • pandora.LinkBean.class

Two files are shared between the referrer part and the core of the distributed application:

  1. pagebox.css

  2. logo.gif

We suggest you to:

  • Setup the keystore as described on the download page.

  • First run the referrer pages of the distributed application

  • Then to copy the referrer part in another Web application with its own authentication mechanism and rerun the demo

  • Then to eliminate login.jsp and adapt link.jsp to collect the name and address info from your application

Go on the login.jsp form of the distributed application.

In the example above the URL is:

http://localhost:8080/PageBox1/distributed/login.jsp

Where:

  1. http://localhost:8080 is the Tomcat URL

  2. PageBox1 is the root-path defined in the rules.xml of the distributed.war PageBox

  3. distributed is the archive name

  4. login.jsp is the name of the form

You must enter four fields:

  1. Name that contains information needed by the payment server to charge the customer

  2. Address that contains information needed by the delivery server to deliver the good to the user

  3. Payment URL is the URL of the payment Web service

  4. Delivery URL is the URL of the delivery Web service


Because the payment and delivery Web service are implemented by paydeliver.war and installed by PageBox, in our case their URLs are made of:

  1. http://localhost:8080, the Tomcat URL

  2. PageBoxSub2 is the root-path defined in the rules.xml of the PageBox used to host the payment Web service and PageBox2Sub2 is the root-path defined in the rules.xml of the PageBox used to host the delivery Web service

  3. paydeliver is the archive name

  4. jaxrpc/QueryIF is the path of the Query Web service, defined in the paydeliver.war’s web.xml

Then click on the Login button. Then you may briefly see the link.jsp page before being displayed the command form.

Command

Select an article from the article dropdown list. Its price should then been displayed in the Unit price field.

Enter a number of articles in the quantity field and click on the Update.

Your command item should then move in the top table.

You can continue adding items. You can also delete and update items with the row buttons of the top table.

Once you are happy with your command click on the Commit button to commit your changes in the database.

Result

You can check that the database tables, command and item were properly updated with the mysql command:

mysql> select * from command;

+----+----------------+-------------+-------------------------------------------

------------------+-------------------------------------------------------------

-+---------------------+

| id | name | addr | payment

| delivery

| date |

+----+----------------+-------------+-------------------------------------------

------------------+-------------------------------------------------------------

-+---------------------+

| 1 | usercreditcard | useraddress | http://localhost:8080/PageBoxSub2/paydeliv

er/jaxrpc/QueryIF | http://localhost:8080/PageBox2Sub2/paydeliver/jaxrpc/QueryIF

| 2003-01-07 00:00:00 |

| 2 | usercreditcard | useraddress | http://localhost:8080/PageBoxSub2/paydeliv

er/jaxrpc/QueryIF | http://localhost:8080/PageBox2Sub2/paydeliver/jaxrpc/QueryIF

| 2003-01-07 00:00:00 |

| 3 | usercreditcard | useraddress | http://localhost:8080/PageBoxSub2/paydeliv

er/jaxrpc/QueryIF | http://localhost:8080/PageBox2Sub2/paydeliver/jaxrpc/QueryIF

| 2003-01-07 00:00:00 |

+----+----------------+-------------+-------------------------------------------

------------------+-------------------------------------------------------------

-+---------------------+

3 rows in set (0.03 sec)

mysql> select * from item;

+------+-----+-----+

| cdid | aid | qty |

+------+-----+-----+

| 1 | 1 | 4 |

| 1 | 3 | 10 |

| 2 | 0 | 6 |

| 2 | 2 | 12 |

| 3 | 0 | 4 |

| 3 | 2 | 5 |

+------+-----+-----+

6 rows in set (0.44 sec)

Every period the distributed application calls the central application’s Update Web service to send the commands recorded so far. Then

  1. The distributed application clears these commands in its database and updates its article inventory with the Update response

  2. The central application inserts these commands in its database and calls the Query Web service of the payment and delivery servers

You can check the database changes in the databases of the distributed and central application and the payment/delivery Update calls in the PageBox log.

Neigbor

If you click on the neighbors link of the command page you are displayed the list of the PageBoxes hosting the distributed application subscribed by the same subscriber on the same Repository:

This list demonstrates the use of the getClones method of the PageBoxAPI.

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