Enhancements to IBM WebSphere Commerce Studio
Version 5.4
As you customize the IBM WebSphere Commerce environment, you will find that you accumulate a number of resources: HTML, JSP, XML documents and Java™ source. To manage and preserve these assets, you will need to set up a source control management system for your team. A source control management system will centralize your team's assets and automatically preserve all of the modifications that are made to these assets. There are many proven source control systems on the market such as Rational® ClearCase® and Concurrent Versions System (CVS). Each member of your team can be assigned a unique user ID that will help you track who is making what changes. Additionally, you will be able to track and manage defects and features. Keeping track of what changes are being made and why is essential for any software project. It is the best way to track a project to completion. If you do not take control of the project, then you can expect your team members to continue to add new features and to modify existing code and so the application will never stabilize.
There are many development tools available for developing Java code and web assets. In this article, we use Rational ClearCase Integration with WebSphere Studio Application Developer (also referred to as WebSphere Studio in the rest of this document) as an example to demonstrate the team development environment
The majority of the assets that you store in your software control management system will be flat text files. For example, you should store the Java source files instead of the class files or JAR files. The software control management system will allow you to organize your files into a directory structure. You should choose a directory structure that matches as closely as possible the target directory structure. For example, if an HTML file is intended to be in a subdirectory stores/web/index.html, then choose the same directory structure and file name for the file in the software control management system.
Once you have all of your resources in a centralized location, you need to develop a process for distributing your application to your test machines, to your production machines, and to your developers. This distribution process can be divided into three steps: building, packaging, and installing.
Building consists of converting your assets from their source form to the form that is required by the application. For example, Java source files need to be converted to Java class files. Many of your assets do not need to be built since they are already in a format that is directly consumable by the application. For example, JSP files do not need additional conversion.
Packaging consists of bundling up all of the application assets into an archive that can be easily distributed. The archive should be made available in a centrally accessible location such as ftp site.
The final step is the install step. Once the packaged archive is downloaded to the appropriate install machine, then it must be installed. Installing will require that the assets in the archive be unpacked and copied to their appropriate locations. It may also involve updating configuration files, deploying enterprise beans and updating the database with additional configuration information.
The rest of this article describes a specific example of a build process. In this example, the Customer Profiles Component of WebSphere Commerce is customized to add a new implicit attribute. The new attribute is "beverage preference". Once installed, the marketing manager will be able to create customer profiles that categorize users according to their beverage preference. The "beverage" attribute is stored in a new table called "beverage". A new enterprise bean is deployed to access this attribute.
This example uses Rational ClearCase LT as the software control management system but all of the concepts described here will be transferable to another version control system.
The first step is to set up the configuration management system. Rational ClearCase LT has a client install and a server install. Choose the machine on which you will store the application assets and run server component. Ensure that this machine is backed up regularly. Once the server component is installed, you will need to create a VOB (Versioned Object Base) to contain the files and directories. Before you can put any of the assets into your VOB, you will need to create a view. Once the view is created, then the files and directories can be added to the view and put under source control management.
All of your developers will need to install the client component. And for each development machine using WebSphere Studio, you need to install Rational ClearCase Integration with WebSphere Studio (which is an extension component that is optionally installed during the WebSphere Studio installation process).
Each developer will need to create his own view from which files can be checked out, checked in, created and deleted.
You need to connect to Rational ClearCase within the WebSphere Studio environment before you can begin using those Rational ClearCase functions that require access to Rational ClearCase servers. Click the Connect to Rational ClearCase button on the Rational ClearCase toolbar before you perform functions that require access to Rational ClearCase servers. The integrated user interface incorporates common functions provided by WebSphere Studio and Rational ClearCase functions. Within the WebSphere Studio environment, you may specify that new project objects or elements be placed under the control of Rational ClearCase. To do this, right-click on the file and choose Team > Add to Source Control. The Add Element to Source Control dialog box appears and you can place the element under Rational ClearCase control. Then you can perform a variety of change management functions. (For details, please refer to the document comes with Rational ClearCase Integration with WebSphere Studio Application Developer: cc_wsappdev.pdf)
For a customization scenario, you may have two different file sets.
The Java code and web assets are developed using an J2EE application development tool,
such as WebSphere Studio Application Developer (in this
example, the files under workspace
directory). And
you may also have external WebSphere Commerce files sitting on our file system, such as schema and data
files (in our example these files are under drive and java directories).
In general, the following files within the Application Developer environment should be version-controlled in ClearCase, either in a staging VOB for that purpose or in their development location:
The following list is the directory structure used for the example.
It only shows the directories that are under source control. Subdirectories are indented
under their parent directories.
WCS_Ref_Apps
buildjars
tools
wsad_customer_profile
driver
META-INF
wcs
bin
schema
db2
oracle
xml
xml
tools
segmentation
java
com
ibm
mycompany
install
workspace
wcs.examples
src
java
com
mycompany
membergroup
commands
tools
segmentation
WCSExample-ejb
ejbModule
com
mycompany
ejbs
META-INF
Schema
The following table describes each of the directories in more detail.
Directory |
Description |
Contents |
|
This directory corresponds to the VOB name. This is the root directory. |
|
|
This directory contains dependency JAR files that are used to build the Java source in this project. These JARs are taken from the current version of IBM WebSphere Application Server and IBM WebSphere Commerce. |
|
|
This directory contains tools files that are used to convert the EJB metadata files for Oracle and iSeries™. These files are taken from the current version of IBM WebSphere Commerce. |
|
|
This is the root directory for the sample application. |
|
|
This directory contains the assets that will be built into the installable archive. |
|
|
This directory contains the |
|
|
This directory contains assets that need to be installed in the root directory of IBM WebSphere Commerce. |
|
|
This directory contains XML assets required by this application. |
XML assets |
|
Executables required to install and configure this application. |
|
|
Assets required to alter and populate the database. |
|
|
SQL scripts specific to DB2. |
|
|
SQL scripts specific to Oracle. |
|
|
Massloader XML documents. |
|
|
This directory contains the Java source for install utility. |
Java source files are located in directories that model their package names. |
|
This directory contains the WebSphere Studio Application Developer workspace projects. |
|
|
This directory is the WebSphere Studio Application Developer workspace for java project wcs.examples. |
Java source files are located under src/java in directories that model their package names in WebSphere Studio Application Developer workspace. |
|
This directory is the WebSphere Studio Application Developer workspace for ejb project WCSExample-ejb. |
|
|
This directory contains the Java source and the assets that will be built into the beverage enterprise bean JAR. |
Java source files are located in directories that model
their package names in WebSphere Studio Application Developer
workspace. |
|
This directory contains XML and XMI documents that contain meta information for the enterprise bean JAR. |
|
|
This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR. |
|
It is this source tree that you should place under source control.
The
contents of this source tree are available in the attached SourceTree54.zip file. This ZIP file excludes
dependency JARs found in the buildjars
directory. In order to run the build, you will need to copy these JARs
from your installation of IBM WebSphere Commerce
and IBM WebSphere Application Server and place them in
the buildjars
directory. The first two can be found in the IBM WebSphere
Application Server lib
directory. The other JARs can be found in the lib and wc.ear/lib
directories in the IBM WebSphere Commerce root directory.
ivjejb35.jar
j2ee.jar
wcsejbimpl.jar
wcsejsclient.jar
wcslogging.jar
wcsmcruntime.jar
wcsruntime.jar
wcssfc.jar
Special
attention should be paid to the build.xml document. This example uses Apache
Ant to perform the build. Ant is a Java-based build tool like the make tool. The build.xml
document contains the instructions that Ant uses to build the application. To run this
build you will need to download a copy of Ant and ensure that the ant/bin directory is in
your path. Then make the wsad_customer_profile directory your current
directory and issue ant.
(For more information about Ant refer to http://jakarta.apache.org/..) The build.xml
document contains additional documentation on the build process. The basic build process
is as follows:
lib directory in the driver/ear directory. beverageEJB.DB2.jar, beverageEJB.Oracle.jar and beverageEJB.OS400.jar) are
packaged up into the driver/ear
directory. The EJB metadata files and isolation level have been converted respectively
before the generation of the EJB JAR. During your real development, considering the amount
and size of EJBs, you may optionally generate only one EJB JAR
file for your environment. packagedDriver.
Before
you start the build you will need to ensure that java.exe is in your path. You should ensure that the
IBM Developer Kit, Java Technology Edition you are using is the same as the one shipped with your version of IBM WebSphere Application Server.
Once
the application has been built, it needs to be installed. In this case the install utility
is built when the driver is built. It is packaged into the driver JAR file and can be run
by issuing java -jar driver-yyyymmdd.jar WAS|WSAD. The install utility source can
be found in java/com/mycompany/install/InstallDriver.java.
To
install the sample to the WebSphere Application Server runtime environment, start WebSphere
Application Server and stop the WebSphere Commerce enterprise application.
For
Windows and UNIX, from command line, issue
java -jar
driver-yyyymmdd.jar was
For
iSeries,
Open
an iSeries green session. Start QSHELL session by running: QSH.
In QSH shell session, issue
java
-Dos400.runtime.exec=QSHELL -jar driver-20030114.jar was
*Notes:*
OS/400® should be V5R2 and make sure PTF S107040 is applied. For V5R1 system, you have to
run the SQL script manually to alter the schema before you run the above install command.
At a high level the utility performs the following tasks:
To install the sample into your WebSphere Studio development environment, close WebSphere Studio Application Developer, then from a command line, issue
java -jar driver-yyyymmdd.jar
wsad
At a high level the utility performs the following tasks:
Examine
the Java source file for further information about what it does. The install program
assumes that you have already installed and configured IBM WebSphere
Commerce and have java.exe in your path.
Once you have your source files in a software control management system and have the build, package, and install processes in place, you should automate your build process and have it run every day. An automated build process will ensure that the latest driver is always available.
Here are the instructions for just using the part of the sample that adds one or more EJB JARs to an existing Commerce application:
The build creates a JAR called installutil.jar that gets placed in CommerceServer/lib during the install. This JAR is used by the install to install the sample. It can also be used to directly add your own new EJB modules to the application:
1. Copy the new EJB JARs to the EAR directory. These JARs should already contain their deployed code.
2. Ensure that WebSphere Application Server is running and the WebSphere Commerce application is stopped.
2. Make CommerceServer/lib your current directory.
3. Enter the following command:
On Windows:
java -cp xml4j.jar;installutil.jar com.mycompany.install.util.InstallEJBHelper <ejbjar1>.jar <ejbjar2>.jar....
On AIX®:
/usr/WebSphere/AppServer/java/jre/bin/java -cp xml4j.jar:installutil.jar com.mycompany.install.util.InstallEJBHelper <ejbjar1>.jar <ejbjar2>.jar....
Note: as part of the process, this utility will rename the WebSphere Commerce EAR to a backup directory to get it out of the way when the application is deleted out of WebSphere Application Server. So, before issuing the command you will need to ensure that no applications are using that directory.
The
first step for automating your build process is to create a Rational ClearCase
snapshot view that will be used to perform the automated build. This can be done using the
Rational ClearCase Create View wizard. Once the view is in
place, then you can use it to perform your automated builds. Rational ClearCase
LT includes an executable called cleartool.exe that can be used to issue ClearCase commands from the command line. This utility will be used
to update the snapshot view with all of the changes that were made since the last build.
Examine the attached file RefAppBuild.bat for an example of a BAT file
that will perform the build. In this example the snapshot view can be found in the d:\extract directory.
The BAT file file makes d:\extract the current directory and then uses the cleartool.exe to update
the view. Then the wsad_customer_profile directory is made the
current directory and the Ant tool is used to clean up the last build and start the new
build.
The
final step for automating your build is to schedule the build script. There are many
applications that will run scheduled jobs. In the attached file, jobScheduler.jar,
there is a Java program that will run a specified list of jobs at a specified time every
day. This program takes as a parameter a file which contains a list of jobs. See the
attached file, joblist, for an example of this file. Notice
that the output of the build is directed to a log file, RefAppBuild.log.
An instance of this log file is included in the package for your reference. In order to
invoke the scheduler program issue java -jar jobScheduler.jar joblist. On Windows NT® or Windows 2000 you can
create a shortcut for this job and add it to your Startup folder so that it will be active
every time you reboot your system. Someone on your team should be assigned to checking the
build log file to ensure that the job completed successfully.
If you have followed all of these steps, then you will have built the framework for a controlled team development process. All of the changes that your developers make will be tracked and when mistakes are made, you will be able to detect them and if necessary, return to a previous version of the application.
The following are trademarks or registered trademarks of IBM Corporation in the United States and other countries:
AIX DB2 IBM iSeries WebSphere
UNIX is a registered trademark of The Open Group in the United States, other countries, or both.
Rational and ClearCase are registered trademarks of International Business Machines Corporation and Rational Software Corporation, in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Windows and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
**************************************************************************