Plants By WebSphere

Overview

Getting Started

Development and Build

Application Install and Management

Run the Application

Technotes

Javadoc

Overview

Plants by WebSphere is an Internet storefront that specializes in the sale of plants and gardening tools. Using the Plants by WebSphere store front, customers can open accounts, browse for items to purchase, view product details, and place orders.

This sample is designed using a typical Java EE web Model-View-Controller (MVC) pattern. The MVC pattern provides separation of concerns for persistent data, presentation of information, and the control logic that is used to tie them together. The sample has been updated to utilize the following technologies:

  • For the presentation tier, Plants By WebSphere uses a combination of JSF 2.0 and Facelets.
  • The controllers are a combination of Managed Beans and EJB session beans.
  • The model portion is generally handled by JPA, though some presentation side wrapping is done to provide additional presentation support. A Derby database provides persistence for a catalog, inventory of items, order handling, as well as a simple user registry.
  • All of the above is tied together using CDI.

One interesting point to note is that now it is no longer necessary to physically separate all these things into different modules. You can create controllers as Managed Beans and package them in your WAR files and as your needs grow to include transactions and security, you can add EJB annotations to those Managed Beans and still access them directly from JSF without having to repackage your application or refactor your code.

Getting started

It is recommended that you copy the install_root /samples directory to your own work area and use it for any samples development. This will prevent any changes you are making to the samples from being overwritten when service updates are applied. Any references to directory locations used in this document will use the installed sample location for clarity only.

Important Information  The instructions assume the application will be built on a Linux system. Small variations in the commands may exist on Windows systems.

Development and Build

The sample comes with a pre-built version of the Plants By WebSphere application, which can be found in the following directory:

install_root /samples/PlantsByWebSphere/pbw-ear/target

If you want to jump ahead and try it out, see the Application Install section.

The sample was developed using Rational Application Developer (RAD), but the build environment has been setup to use Apache Maven. The sample can be used for further develop and test either as is or imported into a set of projects in Rational Application Developer.

If you want to use both RAD and Maven together, you should obtain and read the Java EE Development using Rational Application Developer 7.5.5 and Maven white paper. The rest of this document will assume the exclusive use of Maven as a build environment and a basic text editor for changing files.

Identifying the directory structure

The directory structure of the sample follows the guidlines for building Java EE applications using Maven:


install_root /samples/PlantsByWebSphere Contains the Sample source code for the Plants by WebSphere sample and is organized as a heirarchy of Maven projects. Source is generally found in the src subdirectory of each Maven project.
install_root /samples/PlantsByWebSphere/target/site/apidocs Contains the Javadoc documentation for the sample. This directory is created during the Plants by WebSphere sample maven build.
install_root /samples/PlantsByWebSphere/.../target The target directory contains the build generated files. Each maven sub-project will build a portion of the sample, typically a module. The pbw-ear project assembles the modules and builds an EAR file. The parent project provides overall project definition and handles the build of javadoc.

Prerequisites

You will need to obtain and install Maven 2.2 or later prior to building the sample. See http://maven.apache.org/index.html for more information about Maven.

The POM files for the Plants by WebSphere project assume two things:

  • The WAS_HOME environment variable has been set to the install location of the WebSphere Application Server.
  • The Java EE API jar has been added to a local maven repository for use during the maven build.

You can set WAS_HOME by executing install_root/bin/setupCmdLine .

You can add the Java EE API jar to the local maven repository by running the following command (be sure the Maven bin directory is in your PATH):

mvn install:install-file -Dfile=$WAS_HOME/dev/JavaEE/j2ee.jar -DgroupId=com.ibm.websphere -DartifactId=java-ee-apis -Dversion=6.0 -Dpackaging=jar -DgeneratePom=true

Building the sample

To rebuild this sample, verify that profile_root/bin is in your PATH environment variable. Follow these steps to rebuild the sample:

  1. At the command line, change to the install_root /samples/PlantsByWebSphere directory.
  2. Run maven:
  3. mvn install site


This will compile the Java code, package the modules, package the ear, and create the Javadoc . The ear file will be located in the pbw-ear/target directory and the Javadoc will be located in the target/site/apidocs directory.

Application Install and Management

WebSphere provides multiple ways to install an application. In addition to the typical console and scripting styles, a new style focused on supporting application development with batch build environments has been added called monitored directory deployment. This document will focus on that style of deployment.

Monitored directory deployment allows a developer to install an application on an application server and start it simply by copying the application to a directory. The application is uninstalled by removing the file from the monitored directory.

Prerequisites

There are three aspects that must be addressed when using monitored directory deployment:

  • ensuring that necessary resources are available
  • ensuring that necessary resources are configured
  • enabling the monitored directory deployment service


The Plants By WebSphere sample uses a Derby database, which must be setup before running the application. The application assumes the Derby database will be installed in install_root/Derby/databases. Use the following commands to setup the Derby database before installing and running the Plants by WebSphere sample application:

cd install_root/Derby/databases
jar xf ../../samples/PlantsByWebSphere/Derby/PLANTSDB/pbw-db.jar

The Plants By WebSphere sample uses an enhanced EAR to capture the deployment configuration information for the EAR. This information creates the resources required by the application to access the Derby database as well as a resource for a mail provider. The mail provider resource is a dummy mail provider that will attempt to send mail to a fictitous SMTP server.

The enhanced EAR data was configured using RAD and saved as part of the EAR file metadata in the pbw-ear sub-project. If you want to change the location of the Derby database, you will also need to update the resource configuration within the enhanced EAR metadata and rebuild the sample.

Applications may be installed in WebSphere by copying the EAR file to a well known location and can be uninstalled by removing the EAR file from that location. However, this is not turned on by default. Monitoring may be turned on by using the following command:

  1. In the Integrated Solutions Console, click Applications > Global deployment settings.
  2. Click the check box to Monitor directory to automatically deploy applications. Note: remember the directory location used here.
  3. Apply the settings, Save your changes, and restart the server.

Once this is complete, the Plants by WebSphere application may be installed by copying it to the directory location specified in the Global deployment settings panel.

Important Information  The monitored directory location listed in the console is only the root of a collection of monitored directories. Each server will have a unique sub-directory location that is used under that root directory.

Installing the Plants by WebSphere sample application

The Plants by WebSphere application may be installed by copying it to the directory location specified in the Global deployment settings panel. The following example assumes typical profile and server names, but may need to be modified for your particular case:

cd install_root/samples/PlantsByWebSphere/pbw-ear
cp target/pbw-ear.ear install_root/profiles/AppSrv01/monitoredDeployableApps/servers/server1

To uninstall the Plants by WebSphere application, just delete the EAR file from the monitored directory location.

A developer will typically keep an eye on the log file to understand when application deployment has completed and watch for errors. If you are not using an IDE, such as RAD, that monitors the log, you can use:

tail -f install_root/profiles/AppSrv01/logs/server1/SystemOut.log

When the application install completes, a log message that is similar to the following should be visible:

[2/5/11 8:59:28:765 CST] 0000001c AppManagement I CWLDD0021I: Event id 1794713772-1. Application pbw-ear is started on: WebSphere:cell=stutzNode01Cell,node=stutzNode01,server=server1,status=success.

Configuring mail resources (optional)

The Plants by WebSphere application makes extensive use of annotations for describing metdata about application requirements. While this, in general, can improve developer productivity, it can have some drawbacks. Components that use resource injection require that the resource be defined and references bound to it in order to resolve injection during component startup. This is true, even if the component may not use the resource in a scenario. For example, if a developer is working on updating the UI page flows, they probably don't care exercise the logic for sending an email message for order processing. However, the injected resource chain (ShoppingServlet > MailerBean > mail Session) would require that a mail provider be configured.

A fictitous mail provider for the Plants by WebSphere Sample has already been included in the enhanced EAR. If you do not want to send an order confirmation e-mail, skip this section. The following steps describe how to update the enhanced EAR's mail resource:

  1. Edit the file install_root/samples/PlantsByWebSphere/pbw-ear/src/main/application/META-INF/ibmconfig/cells/defaultCell/applications/defaultApp/deployments/defaultApp/resources.xml
  2. Find the text mailTransportHost="somehost.com" and change it to a valid SMTP server host.
  3. Rebuild the application as described above

Run the Application

To run the application, click the following link:

http://localhost:9080/PlantsByWebSphere

Note the link assumes that the application has been installed on a local server with the typical HTTP port and the WebSphere environment has been appropriately configured. If your installation is not local or does not use the default HTTP ports, you will need to update the URL accordingly.