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

IBM® WebSphere® Commerce

Version 5.4

Last Updated: May 22, 2002

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.

This article does not make reference to any development tools such as IBM VisualAge® for Java for developing Java code or IBM WebSphere Studio for developing your web assets. Your developers are encouraged to use these and other development tools to complement 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 IBM WebSphere Commerce Business Edition 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. Each developer will need to create his own view from which files can be checked out, checked in, created and deleted.

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
  customer_profile_sample
    beverageEJB.ear
      META-INF
    beverageEJB.jar
      META-INF
        Schema
    driver
      ear
        wctools.war
          tools
            segmentation
      META-INF
      wcs
        bin
        schema
          db2
          oracle
          xml
        xml
          tools
            segmentation
    java
      com
        ibm
          mycompany
            ejbs
            install
            membergroup
              commands
            tools
              segmentation
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

customer_profile_sample 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
customer_profile_sample This is the root directory for the sample application. beverageEJB.ear directory
beverageEJB.jar directory
driver directory
java directory
build.xml
CustomerProfileSampleReadMe.html
beverageEJB.ear This directory contains the assets that will be built into the beverage enterprise archive. This archive is used to deploy the beverage enterprise bean. META-INF directory
beverageEJB.ear/META-INF This directory contains XML and XMI documents that contain meta-information for the enterprise application. application.xml
ibm-application-bnd.xmi
ibm-application-ext.xmi
beverageEJB.jar This directory contains the assets that will be built into the beverage enterprise bean JAR. META-INF directory
beverageEJB.jar/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
beverageEJB.jar/META-INF/Schema This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR. Schema.dbxmi
driver This directory contains the assets that will be built into the installable archive. ear directory
META-INF directory
wcs directory
ear This directory contains the assets that will be copied to the installed commerce enterprise archive directory. wctools.war directory
wctools.war This directory contains the assets that should be installed in the wctools.war directory in the installed enterprise archive directory. JSPs used by this application.
driver/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 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 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 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 commerce database schema for this application. This script is used if your database is Oracle and your operating system is UNIX.

profileSampleDeploy.bat - This script generates the deployed code for the enterprise bean JAR and installs the application into the IBM WebSphere Application Server. This script is used if your operating system is Windows.

profileSampleDeploy.sh - This script generates the deployed code for the enterprise bean JAR and installs the application into the IBM WebSphere Application Server. This script is used if your operating system is UNIX.

profileSamplePopulatedb.db2.bat - This script populates the 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 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 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 commerce database with configuration information. This script is used if your database is Oracle and your operating system is UNIX.

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. Java source files are located in directories that model their package names.

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 Business Edition 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

It is this source tree that you should place under source control.

Special attention should be payed 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 customer_profile_sample directory your current directory and issue ant. (For more information about Ant refer to http://jakarta.apache.org/ant/index.html.) 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. beverageEJB.jar is packaged up into the beverageEJB.ear directory.
  3. beverageEJB.ear is packaged up into the driver directory.
  4. 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 JDK 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. The install utility source can be found in java/com/mycompany/install/InstallDriver.java. At a high level the utility performs the following tasks:

  1. Unpackages the driver assets into their appropriate directories.
  2. Modifies the commerce database schema to include any changes required by this application.
  3. Updates the commerce database with configuration information.
  4. Updates the instance configuration XML.
  5. Updates the properties files.
  6. Updates the classpath used by the application to include the new enterprise bean JAR.
  7. Installs the enterprise application that contains the new enterprise bean JAR required by this application.
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 Business Edition and have java.exe is in your path.

Once you have your source 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.

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. Please 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 customer_profile_sample 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     VisualAge(R) for Java      WebSphere   

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Windows, Windows NT and  Windows 2000 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.