Table of Contents Previous Next Index

CHAPTER 1 Introduction : Managing Your Project

Managing Your Project

In general, your development of a deployment project follows these phases:

Setting up the SDK

Creating Your Customizations

Building the Customized Web Application

Deploying the Web Application

Setting up the SDK

To set up the SDK for your project, you must perform the following steps:

1. Decide on a project label for this project: typically this is a short, unique identifier for the deployment. For example, if you are modifying the Matrix reference application, you might choose “matrix80” as the project label. We refer to this project label as project.

2. Check whether the release on which you want to build your project is installed already in the SDK.

a. If the release is installed, run the switchdebs target to set the current default release to the desired release. For example:

sdk switchdebs debs-8.0

Skip to Step 4.

b. If the release is not installed, copy the Sterling.war Web application file and content JAR file for the release to a temporary location on your machine.

3. Run the install target:

a. For releases later than Release 6.3, using SDK Archive files:

sdk install <Location of Comergent.war file>
sdk install <Location of documentation JAR file>

This creates a sub-directory for the release under sdk_home/releases/ and extracts all of the Web application files from the specified Comergent.jar file. For example:

skd install C:\temp\Comergent-7.0.1-def-7_0_1-RC2.jar
sdk install C:\temp\doc-7.0.1-def-7_0_1-RC2.jar

The second execution of the install target installs the product documentation (SDK index docs, Javadocs, ERD diagrams, and PDF Guides).

b. For releases prior to Release 6.3.1, to populate the release directory with the files for this release of the Sterling Multi-Channel Selling Suite:

sdk install <release> <Location of Comergent.war file>
<Location of Content.jar file>

Specify exactly the correct form of the release string. This creates a sub-directory for the release under sdk_home/releases/ and extracts all of the Web application files from the specified Comergent.war file. For example:

sdk install debs-6.3.1 C:\temp\Comergent.war
c:\temp\sdk-content-debs-6.3.1.jar

4. Run the newproject target to create directories for this project. Enter:

sdk newproject <project>

This creates a project directory called sdk_home/projects/project/. It also creates a copy of the release in sdk_home/builds/project/.

5. Install the database files:

a. If you are running against a SQL Server database server, run the installMSSQLJDBC target:

sdk installMSSQLJDBC <full path to JAR file>

You must specify the location of the JAR or ZIP file that provides the JDBC drivers for your SQL Server database server. For example:

sdk installMSSQLJDBC C:\MSSQLJDBC\sqljdbc_1.1\enu\sqljdbc.jar

b. If you are running against an Oracle database server, run the installOracle target:

sdk installOracle <full path to JAR file>

You must specify the location of the JAR or ZIP file that provides the JDBC drivers for your Oracle database server. For example:

sdk installOracle C:\oracle\ora90\jdbc\lib\classes12.zip

c. If you are running against a DB2 database server, run the installDB2 target:

sdk installDB2 <full path to JAR file>

You must specify the location of the JAR or ZIP file that provides the JDBC drivers for your Oracle database server. For example:

sdk installDB2 C:\IBM\SQLLIB\java\db2jcc.jar

d. (Release 6.4.1 to Release 7.1) If you are running against an SQL Server database server, then run the installODBC target:

sdk installODBC

e. (Release 6.0 to Release 6.3.1) If you are running against an SQL Server database server, then run the installMsSql target:

sdk installMsSql

6. Run the env.setDBType target to specify the database type for this project with one of the following:

sdk env.setDBType Oracle
sdk env.setDBType MSSQLJDBC
sdk env.setDBType DB2
(Releases earlier than 7.1) sdk env.setDBType ODBC

7. In the project directory, modify the project_env.properties files to ensure that the correct values are set for the project properties, particularly those of the database connections. In general, you must set values for the machine name of the database server and the username and password you want to use to create the database schema in the database server. For Oracle, you must also provide the TNS alias used to connect to the database from the SDK machine. This is the ORACLE_DATABASE property in the properties file.

Note that you will probably use different database connections for your development (dev), QA (qa), and production (prod) environments. (See Environments for information about managing project environments.) The deploy.environment property of the sdk_home/sdksettings.properties file determines which environment is active at any moment. For example, if the sdk_home/sdk-settings.properties file reads:

project.name=matrix
deploy.environment=dev

then the sdk_home/projects/matrix/matrix_dev.properties file determines the database connection information.

8. If you are installing your Web application into a Servlet Specification 2.2‑compliant servlet container, then run the setservletspec2.2 target:

sdk setservletspec2.2

Note:

The setservletspec2 target works acts on the current project. If you start a new project, you must run this target again to deploy the new project into a Servlet Specification 2.2compliant servlet container.

The Sterling Multi-Channel Selling Suite Implementation Guide provides a table of Servlet Specifications are supported for each servlet container.

9. Run the merge target: this copies the release to the sdk_home/builds/project/ directory. It merges the project properties that you set in Step 7 into the build.

10. Run the createDB target. This creates the database schema (tables, views, procedures, and so on) in the database specified by the connection properties set in Step 7. Log files are created as the schema creation scripts run: you should check these to ensure that no errors have occurred. Typically, errors can occur if you do not run merge before running this target or if you have made an error in entering the properties. Note that if you are running against a DB2 server, then you must open up a DB2 command window first using the db2cmd command, and then run the createDB target in this window.

11. Run the loadDB target or the loadMatrixDB target: the former populates the Knowledgebase with the minimal data for the Sterling Multi-Channel Selling Suite; the latter populates the Knowledgebase with the full Matrix reference data.

12. Run the sdk dist target. This creates a new Sterling.war file that you can now deploy to your servlet container. When you deploy it, the Web application is already configured to connect to the right database and the Knowledgebase is already populated with either the minimal or reference data, so that you can log in to the Sterling Multi-Channel Selling Suite and start testing it.

Creating Your Customizations

Typically, when you customize the Sterling Multi-Channel Selling Suite, you make modifications in these main areas:

the Java classes that comprise the business logic of the system

the JSP pages used to present content to users

configuration files

the XML schema definitions of the set of data objects

the database schema to reflect the changes made in the XML schema

You can use the sdk customize target to select files from the sdk_home/releases/release/ source directories for customization. Enter:

sdk customize <filename>

The file is copied from the release directory identified by the debs.version property to the corresponding sdk_home/projects/project/ directory. For example:

sdk customize AdvisorMessageTypes.xml

copies the file sdk_home/releases/release/WEB-INF/properties/AdvisorMessageTypes.xml to sdk_home/projects/project/WEB-INF/properties/AdvisorMessageTypes.xml.

The structure of the project sub-directories is modeled on the structure of the Web application which is based on the J2EE specification as described in the Sterling Multi-Channel Selling Suite Developer Guide. Additional project directories are provided for the source files (src/)and the configuration file templates (templates/). Note that you do not have to include “src”, “web”, “WEB-INF” in the file names: these are included automatically.

Java classes: in general, you should not need to modify any of the Java classes that comprise the Sterling Multi-Channel Selling Suite application delivered in the Sterling.war file. Your goal should be to customize the business logic of the system by extending classes. The sub-classes should follow a consistent naming convention that reflects the parent’s class package and name.

For example, to modify the way that the com.comergent.apps.catalog.advisor.AdvisorProductDetailController class works, create a new class in the same package structure called MatrixAdvisorProductDetailController. This class should extend the AdvisorProductDetailController class and you can overwrite any methods described in the SDK Javadoc documentation.

Maintain these class files in sdk_home/projects/project/src/com/ so the changes can be merged with the standard Sterling Multi-Channel Selling Suite class hierarchy.

JSP pages: You can customize existing JSP pages or create new ones. Simply follow the guidelines described in the Sterling Multi-Channel Selling Suite Developer Guide.

Configuration files: Typically, you will customize configuration files either to modify the logical flow of the Sterling Multi-Channel Selling Suite using the MessageTypes.xml files, or to add parameters required by the customized business logic. These files should be maintained in sdk_home/projects/project/WEB-INF/properties/ so the changes can be merged with the standard Sterling Multi-Channel Selling Suite configuration files.

Data objects: New data objects created by your implementation or changes to existing data objects must be maintained in your sdk_home/projects/project/WEB-INF/schema/ directory so that they can be deployed along with the standard Sterling Multi-Channel Selling Suite data objects.

Customizing Configuration Files

Typically, you will make two sorts of changes to configuration files during the customization of your project:

Tokenizing Properties

Adding Properties

Tokenizing Properties

If you want to change a property so that it is tokenized, then you must customize the property file in which it is specified.

Using your text editor, edit the file so that the property is defined as a token. For example, this text declares the listPriceDecimalPrecision element as a tokenized property in the Comergent.xml file:

<listPriceDecimalPrecision controlType="text"
runtimeDisplayed="true" ChangeOnlyAtBootTime="false" visible="true"
boxsize="45" displayQuestion="Allowed Decimal Places for displaying
list prices" defaultChoice="2" help="Enter the number of decimal
places displayed for list prices.">@listPriceDecimalPrecision@</list­PriceDecimalPrecision>

Now add a property to your project_env.properties file:

listPriceDecimalPrecision=2

When the project is built, the resulting Comergent.xml will include:

<listPriceDecimalPrecision controlType="text"
runtimeDisplayed="true" ChangeOnlyAtBootTime="false" visible="true"
boxsize="45" displayQuestion="Allowed Decimal Places for displaying
list prices" defaultChoice="2" help="Enter the number of decimal
places displayed for list prices.">2</listPriceDecimalPrecision>

Only files on the list of template files will be processed to have tokens replaced. If you want to add a token to a file that is not on the list, then you must add it:

1. Open sdk_home/etc/templates/8.x/template_files.list and add the file name to the list of files.

2. Save the file.

3. Enter:

sdk customize <File to be tokenized>

4. In the appropriate sub-directory of sdk_home/projects/project/ locate this file, and insert the token using the standard syntax: @TOKEN_NAME@.

5. In the project_env.properties, add a line for this new token and its intended value.

TOKEN_NAME=Token value

6. Run:

sdk merge

7. The file in the sdk_home/builds/project/ directory now has the token value in place of the token.

Adding Properties

If you want to add a property to a configuration file, then you must customize the configuration file in which it is specified. Enter:

sdk customize <Configuration file>

Using your text editor, edit the file so that the property is declared. For example, this text declares the viewAllComments element as a property in the Comergent.xml file:

<viewAllComments ChangeOnlyAtBootTime="false"
controlType="select" button="radio"
multipleChoice="false"
runtimeDisplayed="true"
visible="true" boxsize="45"
displayQuestion="Enable users to see all comments"
displayOptions="true,true,false,false"
defaultChoice="true" help="Allow users to see all comments made
about a product">false</viewAllComments>

When you next build your project, this property is included in the Comergent.xml.

If you want the property to be customizable as a token, then follow the instructions in Tokenizing Properties. For example:

<viewAllComments ChangeOnlyAtBootTime="false"
controlType="select" button="radio"
multipleChoice="false"
runtimeDisplayed="true"
visible="true" boxsize="45"
displayQuestion="Enable users to see all comments"
displayOptions="true,true,false,false"
defaultChoice="true" help="Allow users to see all comments made
about a product">@ViewAllComments@</viewAllComments>

Now add a property to your project_env.properties file, for example:

ViewAllComments=true

When the project is built, the resulting Comergent.xml will include:

<viewAllComments ChangeOnlyAtBootTime="false"
controlType="select" button="radio"
multipleChoice="false"
runtimeDisplayed="true"
visible="true" boxsize="45"
displayQuestion="Enable users to see all comments"
displayOptions="true,true,false,false"
defaultChoice="true" help="Allow users to see all comments made
about a product">true</viewAllComments>

Building the Customized Web Application

Use the merge target to compile the classes and copy over and merge the customizations that you have created in the sdk_home/projects/project/ directory. Check that the deployment source includes all of the files and modifications to files that you expect.

sdk merge

Deploying the Web Application

Use the distWar target to generate the Web application. The Web application is copied and compiled into the sdk_home/dist/ directory, and from there can be deployed to your servlet container.

sdk distWar

Note that the automatically-generated name of the WAR file includes a date stamp and the value of the deploy.environment property defined in the sdksettngs.properties file. The first part of the file name is controlled by the app.name property defined in the default-sdk.properties file. For example, Sterling_20071211_dev.war.

Alternatively, you can use the dist target: this creates a full install JAR file. Use this when you need to pass the SQL database schema creation scripts to a database administrator.

You can also use the deploy target to deploy the Web application to the servlet container environment.

sdk deploy

Note however, that you must take care to modify the SDK properties so that the application is installed into the correct location. Use the container.home and apps.dir properties defined in the my-sdk.properties file to specify the deployment location.

Managing Different Releases

You may find that you are working on different projects at the same time. If the different projects use different versions of the Sterling Multi-Channel Selling Suite, then use the install target to install the new release and the switchdebs target to switch from one installed release to another.

Upgrading Projects

If you build a project against one release of the Sterling Multi-Channel Selling Suite and then you install a new release, then you can upgrade the project to the new release using the project.premigrate, project.migratefiles, and project.postmigratecleanup targets.

You should always run sdk merge -clean after upgrading a project to a new release.