Setting up a controlled team development environment for customizations of IBM® WebSphere® Commerce


Enhancements to IBM WebSphere Commerce Studio

Version 5.4


Introduction

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

Managing resources

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 build process

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

WCS_Ref_Apps

This directory corresponds to the VOB name. This is the root directory.

buildjars directory

wsad_customer_profile directory

buildjars

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.

ivjejb35.jar
j2ee.jar
wcsejbimpl.jar
wcsejsclient.jar
wcslogging.jar
wcsmcruntime.jar
wcsruntime.jar
wcssfc.jar

tools

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. 

wcsconvert.jar

oracle.mapping

os400.mapping

wsad_customer_profile

This is the root directory for the sample application.

driver directory
java directory
workspace directory
build.xml
CustomerProfileSampleReadMe.html

driver

This directory contains the assets that will be built into the installable archive.

META-INF directory
wcs directory

META-INF

This directory contains the MANIFEST.MF file for the driver JAR file.

MANIFEST.MF - indicates the Java class that should be invoked when the driver JAR is executed.

wcs

This directory contains assets that need to be installed in the root directory of IBM WebSphere Commerce.

xml directory
bin directory
schema directory

xml

This directory contains XML assets required by this application.

XML assets

bin

Executables required to install and configure this application.

profileSampleCreatedb.db2.bat - This script alters the WebSphere Commerce database schema for this application. This script is used if your database is DB2® and your operating system is Windows®.

profileSampleCreatedb.db2.sh - This script alters the WebSphere Commerce database schema for this application. This script is used if your database is DB2 and your operating system is UNIX®.

profileSampleCreatedb.oracle.bat - This script alters the WebSphere Commerce database schema for this application. This script is used if your database is Oracle and your operating system is Windows.

profileSampleCreatedb.oracle.sh - This script alters the WebSphere Commerce database schema for this application. This script is used if your database is Oracle and your operating system is UNIX.

profileSamplePopulatedb.db2.bat - This script populates the WebSphere Commerce database with configuration information. This script is used if your database is DB2 and your operating system is Windows.

profileSamplePopulatedb.db2.sh - This script populates the WebSphere Commerce database with configuration information. This script is used if your database is DB2 and your operating system is UNIX.

profileSamplePopulatedb.oracle.bat - This script populates the WebSphere Commerce database with configuration information. This script is used if your database is Oracle and your operating system is Windows.

profileSamplePopulatedb.oracle.sh - This script populates the WebSphere Commerce database with configuration information. This script is used if your database is Oracle and your operating system is UNIX.

profileSamplePopulatedb.os400.sh - This script populates the WebSphere Commerce database with configuration information. This script is used if the operating system is iSeries.

schema

Assets required to alter and populate the database.

db2 directory.
oracle directory.
xml directory.

schema/db2

SQL scripts specific to DB2.

profileSample.schema.sql - SQL script used to alter the commerce database schema.

schema/oracle

SQL scripts specific to Oracle.

profileSample.schema.sql - SQL script used to alter the commerce database schema.

schema/xml

Massloader XML documents.

profileSample.xml - Massloader import document used to populate the commerce database with configuration information for this application.

java

This directory contains the Java source for install utility.

Java source files are located in directories that model their package names.

workspace

This directory contains the WebSphere Studio Application Developer workspace projects.

wcs.examples directory
WCSExample-ejb directory

workspace/wcs.examples

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.

workspace/WCSExample-ejb

This directory is the WebSphere Studio Application Developer workspace for ejb project WCSExample-ejb.

ejbModule directory

workspace/WCSExample-ejb/ejbModule

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.
META-INF directory

workspace/WCSExample-ejb/ejbModule/META-INF

This directory contains XML and XMI documents that contain meta information for the enterprise bean JAR.

Schema directory
ejb-jar.xml
ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-ext.xmi
Map.mapxmi
Table.ddl

workspace/WCSExample-ejb/ejbModule/META-INF/Schema

This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR.

Schema.dbxmi

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:

  1. All of the Java source is compiled into the lib directory in the driver/ear directory.
  2. Generate the EJB JAR file. In this example, to demonstrate the flexibility, three different EJB JAR files (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.
  3. The driver is packaged up into a JAR file and placed in a directory called 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.

Installing

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:

  1. Unpackages the driver assets into their appropriate directories.
  2. Modifies the WebSphere Commerce database schema to include any changes required by this application.
  3. Updates the WebSphere Commerce database with configuration information.
  4. Updates the instance configuration XML.
  5. Updates the properties files.
  6. Generates the deployed code for the new EJB JAR required by this application.
  7. Adds the new EJB JAR to the existing WebSphere Commerce enterprise application.

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:

  1. Unpackages the driver assets into their appropriate directories.
  2. Modifies the WebSphere Commerce database schema to include any changes required by this application.
  3. Updates the WebSphere Commerce database with configuration information.
  4. Updates the instance configuration XML.
  5. Imports the new Java projects and an EJB project into the workspace and build the projects.
  6. Refreshes the existing projects so they will pick up the properties files.
  7. Adds the new EJB module and new utility JAR to the WebSphere Commerce enterprise application.
  8. Adds the new Java Projects to the JAR dependency list of the WAR modules.

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.

Secondary entry point for adding an EJB module to the enterprise application

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.

Automating the build

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.

Conclusion

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.


Trademarks and Service Marks

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.

**************************************************************************
 
** © COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 2002
 
** ALL RIGHTS RESERVED.
 
**************************************************************************

Note to US Government Users -- Documentation related to restricted rights -- Use, duplication, or disclosure is subject to restriction set forth in GSA ADP Schedule Contract with IBM Corp.

End of document.