Command line packaging

 

In this topic ...

Creating a Package at the Command Line

Installing a Package from the Command Line

In some cases, you might want to create or install a package at the command line rather than by using the Add Feature Set menu item. For example, if the contents of a package are updated on a regular or daily basis, it is convenient to automate the assembly and installation of a package (using a script) rather than to manually update the package each time content changes.

Use the information below to learn how to create a package and install a package using command line procedures.

We can also view command line package creation examples and package installation commands and scripts.

Designer packaging is not intended to be used as an application deployment mechanism and is not optimized to manipulate large numbers of files.

  • If we need to package or move a large number of files use standard J2EE mechanisms (such as a WAR file) or a program such as Microsoft's WinZip utility.

  • When moving an application from a staging to a deployment server use a WAR file. This insures that you deploy exactly what you tested and not some super-set or subset of what was tested in the WAR on the staging server.

 

Create a Package at the Command Line

There are two steps to creating a package at the command line:

  1. Create a package manifest file. This file contains important information about the package, including a list of contents. This file must be named manifest.bs.

  2. Create a batch file or script to perform packaging operations.

 

Inside the Manifest File

The Package manifest file is written in XML and it contains a list of the components that comprise the package as well as some meta-data about the package. When the package is created, the specified components are included in the package along with manifest file.

We can create or edit a manifest file with an ordinary text editor, but follow this file's required format (see below). The easiest way to create this file is to build a package using the Designer's packaging tools. Then extract the existing manifest from that package for modification and reuse. Use a utility (such as WinZip) to extract the manifest file from the package.

To edit this file extract it into the directory ../packaging/staging. In essence, you will be editing the <item> nodes within the file and/or the <PackageDescription> meta-data.

Here's an example of a manifest file containing one of each type of component we can package ( model , file, directory, and profile set). Note that the carriage returns are not necessary, but are placed there during packaging:

<Manifest>
<Item
id="my.model"
name="my.model"
type="Models"
>
</Item>
<Item
id="Classes/samples/appletSamplet.class"
name="appletSamplet.class"
type="Files"
>
</Item>
<Item
id="Classes/samples"
name="samples"
type="Directories"
>
</Item>
<Item
id="com.bowstreet.profileset.customizertextarea"
name="com.bowstreet.profileset.customizertextarea"
type="ProfileSets"
>
</Item>

<PackageDescription>
<authorMail>jdoe@company.com</authorMail>
<authorName>j doe</authorName>
<description>Doe's model description</description>
<instructions>Doe's model run instructions</instructions>
<minServerVersion>4.2.1</minServerVersion>
<name>DoeTestPak</name>
<publisher>com.company</publisher>
<status>Alpha</status>
<version>1.2.3</version>
<modelToRun>some_model_ID</modelToRun>
</PackageDescription>
</Manifest>

Packages created using the Designer's GUI-based packaging tools can have an additional Package Description entry titled "ModelToRun" if the package creator has enabled this functionality. The ModelToRun argument is not available at the command line and is ignored by command line operations.

Note that Items represent the components included in the package and that each item is identified by the following tags:

  • ID -- Provides the full path and name of the item

  • NAME -- Provides the item name

  • TYPE -- Identifies the component type (files, directories, models or profile sets)

 

Database Profiles and Command Line Packaging

You must follow some special procedures when using the command-line packaging tool on a Factory system configured for storing profiles in a database. The following steps are required for successful packaging in this setting:

  1. Create a override.properties file in the .../WEB-INF/config/directory. In this file properties must be setup to use JDBC pooled database connections for profile storage. Command line packager can not access J2EE Data Sources, but it can use JDBC pool database connections for profile storage.

  2. Create this override.properties file with the correct properties for using JDBC pooled connections. This allows the packaging tool to access the database profiles. A sample override file might look as follows:

bowstreet.profiles.storage.db.connectionFactory={shared}com.bowstreet.profiles.storagehandler.JdbcPooledConnectionFactoryImpl

bowstreet.profiles.storage.connectionFactory.jdbcUrl=jdbc:oracle:thin:@qaoracle:1521:bowqa002

bowstreet.profiles.storage.connectionFactory.jdbcUserName=daily

bowstreet.profiles.storage.connectionFactory.jdbcPassword=test

bowstreet.profiles.storage.connectionFactory.jdbcVerificationSql=select sysdate from dual

bowstreet.profiles.storage.connectionFactory.jdbcAcquireTimeout=5000

bowstreet.profiles.storage.connectionFactory.jdbcPoolSweepPeriod=30

bowstreet.profiles.storage.connectionFactory.jdbcInactiveConnectionTimeout=30

bowstreet.profiles.cache.waitTime=60

bowstreet.profiles.storage.handler=com.bowstreet.profiles.storagehandler.DbStorageHandlerImpl

  1. Make sure the specific vendors JDBC Driver is listed along with its location in the classpath and set the -Djdbc.drivers property as follows:

For DB2 - Add the following files (including full path info) to the classpath: db2java.zip. Add the following class definition:

-Djdbc.drivers=COM.ibm.db2.jdbc.net.DB2Driver

For SQL Server 2000 - Add the following files (including full path info) to the classpath: mssqlserver.jar;mbase.jar;msutil.jar. Add the following class definition:

-Djdbc.drivers=com.microsoft.jdbc.sqlserver.SQLServerDriver

For Oracle - Add the following files (including full path info) to the classpath: classes12.zip. Add the following class definition:

-Djdbc.drivers=oracle.jdbc.driver.OracleDriver

  1. Add the driver class to the JDBCDrivers.properties file under the /config folder. For example: oracle.driver=oracle.jdbc.driver.OracleDriver

 

Package Create Command

Use the following command to initiate package creation:

com.bowstreet.packaging.CreatePackage

This command can be run from any location. Note however that specify the full path and name of any JAR file used by your models as well as any JARs that support the storage of Profile Sets (such as JDBC drivers).

For example, from <AppServerDeployDir>\myproject.ear\wpf.war a package create command might looks as follows:

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.CreatePackage WEB-INF/packaging/staging/scriptname WEB-INF/packaging/staging/packname

 

Package Naming Conventions

We can name a package anything you like, but is recommended that you use a .pkg extension on all package names. This will enable others to use the packaging tools in the Designer to manipulate the package at a later date.

 

Example - Package Creation Batch File

The batch file you write to initiate package creation requires the following inputs:

  • Manifest File Name - The name of a file that contains a description of the contents of the package to be made

  • Package Name - The name you want to assign to the package you are creating

A typical package creation batch file might look as follows:

The classpath code segment must be one continuous line.

echo off

if {%1}=={} goto usage

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.CreatePackage %1 %2

goto end

:usage
echo create-package makes a IBM .pkg file.
echo create-package takes these arguments,
echo 1. The full path to the package Manifest file. For example: "WEB-INF\packaging\staging\manifest.bs" (file must exist)
echo 2. The full path to the location and name of the package to be created For example: "WEB-INF\packaging\staging\mypak".

:end

echo on

Once this file is created, we can place it in the Factory ../bin directory and run the file from there.

You must specify the full path and name of any JAR file used by your models.

For example, from <AppServerDeployDir>\myproject.ear\wpf.war a package create command might looks as follows:

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.CreatePackage WEB-INF/packaging/staging/scriptname WEB-INF/packaging/staging/packname

 

Installing a Package from the Command Line

Installing a package from the command line lays down package contents in the proper Factory locations and is a convenient way to perform repetitive or frequent installations. This might be the case in a setting where application files are updated on a daily or weekly basis.

 

Package Install Command

Use the following command to initiate installation of a package:

com.bowstreet.packaging.InstallPackage

We can run this command from any location. The install command accepts the following arguments:

  • - verbose -- To output extra information in the console

  • - skip -- To prevent an item from being installed. If an item in the package already exists on the target system, that item is skipped (not installed) during installation.

  • - force -- To overwrite a previously installed component. If an item in the package already exists on the target system, package installation will overwrite the existing item.

When installing a package specify the full path and name of any JAR files used by your models, including JARs related to Profile Set storage.

For example, from <AppServerDeployDir>\myproject.ear\wpf.war a package create command might looks as follows:

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.InstallPackage <ex: -verbose, -skip, -force> WEB-INF/packaging/staging/test-0.0.0.pkg

 

Package Installation Scripts

The following installation procedures describe a typical installation scenario. Two sample installation scripts are provided below. The UNIX script (InstallUnix3x.sh) should be placed in and executed from the: /$IBMInstall$/webengine/bin

The package you want to install must be placed in: /$IBMInstall$/webengine/packaging/staging

Note that the script needs to have "execute-level" permissions.

In addition, the user installing the package must have an admin account on the machine to which they will be installing (i.e., be a user in the "Factory administrators group.") The user name "factoryadmin" is provided as a default administrator account.

 

Script Examples

All package installation commands are executed from the webengine/bin directory. Package installation scripts require the following arguments

  • The name of the install script you want to execute (for example: InstallUnix3x.sh)

  • The name of the package you want to install from the /staging directory

  • The password for the Factory administrator performing the installation.

Example - UNIX Installation Script

The following UNIX script illustrates the content and format of a typical package installation script. Use this example as a basis for creating your own script.

The class path code segment must be one continuous line.)

#!/bin/sh

usage()

{
echo InstallPack.sh installs a Factory package file.
echo InstallPack.sh takes one arguments,
echo 1. The name and the location of the package file to install.
echo For example: InstallUnix2x /home/bowstreet/packaging/staging/myPak.zip
echo For example the command should look like the following:
echo The InstallPack.sh file should be in the bin directory.
echo ./InstallPack.sh ../packaging/staging/myPak.pkg "cn=factoryadmin,ou=bowstreet,o=bowstreet,c=US" welcome
}

echo off

pakToInstall=$1
echo $pakToInstall

if [ "$pakToInstall" = "" ] ; then
usage
fi

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.InstallPackage $pakToInstall

echo on

Example - Windows Installation Script

The following script illustrates the content and format of a typical package installation script. Use this example as a basis for creating your own script.

The class path code segment must be one continuous line.)

echo off

if {%1}=={} goto usage

java -cp WEB-INF/lib/packman.jar;WEB-INF/lib/factory.jar;WEB-INF/lib/clientLibs/sax2.jar;WEB-INF/lib/jakarta-regexp-1_2.jar;WEB-INF/lib/crimson-113.jar -Dbowstreet.rootDirectory="WEB-INF" com.bowstreet.packaging.InstallPackage %1

goto end

:usage

echo install-package makes a Factory .pkg file.
echo instal-package takes these arguments,
echo 1. The full path to the package file. For example: "WEB-INF\packaging\staging\MyPackage.pkg" (file must exist)
 

:end

echo on