

Pet Store Example Overview:
===========================

The Java Pet Store example is the well-known application available on the
java.sun.com site illustrating Blueprints guidelines and patterns about
Enterprise applications and Web services.

It consists of three applications:

- Java Pet Store:
	The main J2EE Blueprints application. 
- Java Pet Store Administrator:
	The administrator module for the Java Pet Store. 
- Blueprints Mailer:
	A mini-application which presents some of the J2EE Blueprints design
	guidelines in a smaller package. 


This $JONAS_ROOT/examples/jps example is the Java Pet Store application version 1.1.2
customized for running on the JOnAS server.



Directory structure:
====================

./jo:
	This directory contains the Pet Store example files specific to JOnAS,
	(i.e. essentially ant build files and XML deployment descriptor files
	specific to JOnAS). It also contains some Pet Store sources that was modified
	to take into account the 'McKoi' database type.

./jps1.1.2:
	This directory must contain the original Pet Store example.
	It's up to you to create it by downloading the Pet Store version 1.1.2.

./jonas-jps1.1.2:
	This directory will contain the Pet Store example customized for running
	on the JOnAS server.
	It is automatically created from the two previous directories via a
	build command.



Downloading Pet Store:
======================

- Download The Pet Store version 1.1.2 example from
    http://java.sun.com/blueprints/code/

- Unzip the 'jps-1_1_2.zip' file under $JONAS_ROOT/examples/jps.

Then, the '$JONAS_ROOT/examples/jps/jps1.1.2' directory will be created.



Customizing Pet Store for JOnAS:
================================

- Under $JONAS_ROOT/examples/jps, do
    $ ant customize4jonas

Then, a 'jonas-jps1.1.2' directory will be created, containing the Pet Store example
sources customized for running on JOnAS.



Configuring this example:
=========================

1) Database configuration:
--------------------------

The Java Pet Store and the Java Pet Store Administrator applications need a
database to run.

a) Configure the customer EJB component to use the correct Data Access Object

The Java Pet Store is configured to use the Cloudscape database by default.
If you're using another database, you must change the configuration of the
Customer EJB component to redefine the Data Access Object it uses.

For that, open the file 'customer_ejb.xml' located in
    jonas-jps1.1.2/src/components/customer/src,
and look for these lines:
  <env-entry>
    <env-entry-name>ejb/order/OrderDAOClass</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>com.sun.j2ee.blueprints.customer.order.dao.OrderDAOCS</env-entry-value>
  </env-entry>

Change the value of the 'env-entry-value' entry to the fully qualified name of the
correct Data Access Object class.
Possibles values are:
  com.sun.j2ee.blueprints.customer.order.dao.OrderDAOCS
    for Cloudscape database,
  com.sun.j2ee.blueprints.customer.order.dao.OrderDAOMcKoi
    for McKoi database,
  com.sun.j2ee.blueprints.customer.order.dao.OrderDAOOracle
    for Oracle database,
  com.sun.j2ee.blueprints.customer.order.dao.OrderDAOSybase
    for Sybase database.

Note that the Data Access Object for Cloudscape works fine for PostgreSQL.

b) Configure a DataSource for JOnAS

As for the other JOnAS examples, you have to configure a datasource.
It's JNDI name must be 'jdbc_1'.

See the chapter 'Configuring Database service' of the JOnAS 'Configuration guide',
for more information.

c) Some warnings about using the McKoi database

- Pet Store works fine with McKoi 0.93b but doesn't work with McKoi 0.94e.
Indeed, in McKoi 0.94e words like 'account', 'password' are identifiers.
There are some discussions on their mailing list.
In order to use McKoi 0.94e (last version when this readme was published),
all the Pet Store code must be changed to take into account theses identifiers.
The code may not be :
   select ... from account
but
   select ... from "account"

- It's important to configure properly the McKoi database.
Pet Store use sometimes lowercase, sometimes uppercase for referencing the tables.
But McKoi use by default case sensitive names, so Pet Store won't run correctly.
In order to work with Pet Store, edit your 'db.conf' property file
and set the property 'ignore_case_for_identifiers' to 'enabled'.

2) Mail factory configuration:
------------------------------

The Blueprints Mailer application needs a mail factory with Session type.
It's JNDI name of the session mail factory must be 'mailSession_1'.

See the chapter 'Configuring Mail service' of the JOnAS 'Configuration guide',
for more information.

3) Tomcat configuration:
------------------------
The following must be done only if you use the single JOnAS Packaging
(the package JOnAS-Tomcat is ready to use)
a) Web container service.
You need to have the web container catalina 4.1 service in your jonas.properties.
jonas.service.web.class	org.objectweb.jonas.web.catalina41.CatalinaJWebContainerServiceImpl

Note that Tomcat 4.1.x is packaged with a webapp admin. Petstore use the context /admin for
the petstore administration, so you have to remove the admin.xml in your $CATALINA_HOME/webapps
or $CATALINA_BASE/webapps in order to deploy the Petstore ears successfully.

b) Tomcat users configuration


The Blueprints Pet Store Administrator application needs a tomcat user.
Add the following line in the $CATALINA_HOME/conf/tomcat-users.xml file:
  <user name="jps_admin" password="admin" roles="administrator" />

(Note that the default content of the jonas-users.properties file already
 includes this user.)

c) JOnAS AccessInterceptor

You must indicate to tomcat to use a JOnAS AccessInterceptor in order to make the
propagation of security context mechanism available.
For Tomcat 4.1.x, this is done by updating the $CATALINA_HOME/conf/server.xml file. 
Replace the line: 
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/>
by 
    <Realm className="org.objectweb.security.catalina41.realm.UserDatabaseRealm"
             debug="0" resourceName="UserDatabase"/>


4) Jetty configuration:
------------------------

a) Web container service.
You need to have the web container Jetty service in your jonas.properties.
jonas.service.web.class	org.objectweb.jonas.web.jetty.JettyJWebContainerServiceImpl


b)Jetty users configuration

The Blueprints Pet Store Administrator application needs a jetty user.
By default, jettyRealm.properties in $JONAS_ROOT/conf contains the
user jps_admin with the password admin.


Building this example:
======================

- Under $JONAS_ROOT/examples/jps, do
    $ ant install

Note that this is equivalent to execute this command under
    $JONAS_ROOT/examples/jps/jonas-jps1.1.2



Running this example:
=====================

1) Run JOnAS server:

The jonas.properties file must specify the following services:
   - registry,jmx,security,jtm,mail,dbm,ejb,web,ear
The jonas.service.ear.descriptors property must contain:
   - petstore.ear,petstoreadmin.ear,mailerapp.ear

   $ jonas start

2) Look at http://<hostname>:<your_port_number>/estore
   to start the Java Pet Store application.

3) Look at http://<hostname>:<your_port_number>/admin
   to start the Java Pet Store Administrator application.

4) Look at http://<hostname>:<your_port_number>/mailerapp
   to start the Blueprints Mailer application.

(The default Tomcat or Jetty http connector port number is 8080)



Miscellaneous
=============

Re-initialization of the database tables using by the Pet Store Application:
----------------------------------------------------------------------------

The first time the Pet Store application is launching, a web page which allows
to create theses tables, appears automatically.
If you want to re-create them later, just look at the
	http://<hostname>:<your_port_number>/estore/populate
page.


Configuring order confirmation e-mail for the Pet Store Application:
--------------------------------------------------------------------

The Java Pet Store can be configured to send a confirmation e-mail to a customer
when an order was completed. This feature is turned off by default.
E-mail order notification can be enabled at deployment time.

Open the file 'estore_ejb.xml' located in
    ./jonas-jps1.1.2/src/petstore/src/estore_ejb.xml,
and look for these lines:
  <env-entry>
    <env-entry-name>ejb/mail/sendConfirmationMail</env-entry-name>
    <env-entry-type>java.lang.Boolean</env-entry-type>
    <env-entry-value>false</env-entry-value>
  </env-entry>

Change the value of the 'env-entry-value' entry to 'true'.

Then, rebuild the Pet Store example.

When using the Pet Store application, don't forget to initialize the customer
email address with a correct value.


