Portlet Factory, Version 6.1.2

 

Automating the generation of WAR files

You can easily automate the creation of Portlet and standalone war files, without a full product install on the build system by using Ant and command line scripting.

 

Automating WAR generation

These commands work well within an existing project. However, on a build machine it makes more sense to only check in the developer contributed content, leaving out the WebSphere Portlet Factory runtime. This greatly simplifies testfix and feature upgrades and reduces clutter in the project.

The ideal source control project environment would contain all of the models, profilesets, java source, config files, dynamic content, and any runtime files that the individual developer may have overridden. Along with the this content, a few other WebSphere Portlet Factory generated files need to exist in the project as well. The following files need to be included on a per-project basis, but are be excluded from the generated war files

 

Setting up your source system environment

Follow these general steps to establish a source system environment.

  1. Set up the .deployment/ folder

    This folder can be found at the project root location. It includes all of the necessary files for generating portlet and standalone war files and several exclude files, which the individual developer can modify (on a per-project basis), to remove certain files from the generated war file. Check in this file into the project root directory.

  2. Use the projectDeploy.xml script is your main script for using Ant tasks to generate war files. This script needs to be in the project's Webcontent Root.Once you have added the project to source control, then add the runtime zip, WebSphere Portlet Factory featuresets, and pbportlet.jar files. Ideally these files would live in a third-party folder. The pbportlet.jar file is not shipped with the product and must be obtained from an existing WebSphere Portal installation. Unless you are expecting to build WebSphere Portlet Factory-Native portlet wars, the jar will not be needed. A project directory structure for third party objects, in source control, might resemble the following: 
    /3rdParty/
  WPF6.1.2/
     /Images/
	factory6.1.2.zip
     /FeatureSets
           BuildingModels.pkg
           collaboration.pkg
           ContentModel.pkg
           etc..	
    /WebSphere Portal
           pbportlet.jar
    Copy the featuresets manually from a existing installation of WebSphere Portlet Factory, and then generate the WebSphere Portlet Factory image file from an Ant task within projectDeploy.xml. This task requires an installation of the WebSphere Portlet Factory to be present during file creation and is generally preformed on a separate system. The WebSphere Portlet Factory Image is a zip file that contains all of the WebSphere Portlet Factory core runtime files that are necessary for an existing WAR. This zip file does not contain the .deployment directory. This image file is essentially the runtime version of the project. You may find it useful to create several different runtime versions of the product if needed. It is also expected that runtime images will need to be recreated when you apply fixpacks and testfixes. Copy fixes that require featureset changes into the suggested third part featuresets directory. You will need to create a new copy of the runtime image for fixes that do not ship with a featureset. The creation of runtime images are discussed in the following section.

 

Ant tasks within projectDeploy.xml you can use to create your own scripts

The following additional Ant tasks in projectDeploy.xml can be used for generating war files in a build environment:

makeFactoryImage (for command line use only)

Use this task to create the factory image zip file for the build system. The WebSphere Portlet Factory image contains the core factory runtime data. This data is gathered from the Templates directory of a WebSphere Portlet Factory install. The task takes two arguments:

runtime.image

name and full path for the exported WebSphere Portlet Factory image zip

image.root

full path to the factory Templates directory, for example: /IBM/Portlet Factory/Designer/FeatureSets/Web-App_6.1.2/Templates
This task should only be invoked to generate an initial WebSphere Portlet Factory image, and to pickup changes made from product fixes and upgrades.

expandFactoryImage

Use this task to expand a generated WebSphere Portlet Factory image zip onto an existing project. Invoke this task before adding any featuresets or compiling of the project. By default the WebSphere Portlet Factory image will not overwrite existing files that the individual developer has checked into their project. Two parameters are required:

runtime.image - the location of the runtime image to extract

project.location - the root project location where the image will be extracted.

addFeatureSet

Use this task to extract a featureset for a given project. Call this task after expandFactoryImage, since it relies on jar files that are contained within the WebSphere Portlet Factory image. Two parameters are used by the task:

pkg – the location of the featureset to install

webcontent.location – factory build WebContent root.

setServerPortDefault

Call this task before generating any war files. It will set the server port in the server.properties file. This task takes three parameters.

webcontent.location - factory build WebContent root.

project.location - the root project location that the image will be extracted to.

http.port - (optional) port number for server (otherwise defaults to 10000)

The other Ant tasks within projectDeploy.xml, with the exception of the build war tasks, can be ignored. These tasks are used exclusively by the WebSphere Portlet Factory designer.

 

Sample script and property files

A sample Ant build.xml, and accompanied build.properties file has been included to aid in generating a build scripts. These files are generic enough to be used in a custom project with little modification. These sample files are located in the Designer\FeatureSets\Web-App_6.1.2\Templates\Project\.deployment\buildsample directory.

The script begins with a nightly target. This is the default task that is called to generate the requested war files. The first task is to generate the dist and buildtmp directories. The dist directory will contain the generated user war files. The buildtmp.location is where the factory image and featuresets are installed. 

<!-- create temp directory structure for building -->
    <mkdir dir="./dist" />
    <mkdir dir="./${buildtmp.location}" />
The next step copies the source objects from the build directory into the build temp directory. 
<!-- create temp dir to build on top of -->
    <copy todir="${buildtmp.location}/.deployment">
      <fileset dir="${buildsrc.location}/.deployment"/>
    </copy>    

    <copy todir="${buildtmp.location}/WebContent">
      <fileset dir="${buildsrc.location}/WebContent"/>
    </copy>
Once the individual developer content has been copied over, the factory image can be installed into the build temp directory. 
<!-- expand factory image into the webcontent.location -->
   <ant antfile="${webcontent.location}/projectDeploy.xml"
            target="expandFactoryImage" >
    <property name="runtime.image" value="../3rdParty/WPF6.1.2/Images/factory.zip" />
   </ant>
The following steps installs the required featuresets into the build temp directory. This must be done after the factory image has been extracted. For each featureset that is installed, a new Ant call must be made. 
<!-- add the required featuresets  -->
    <ant antfile="${webcontent.location}/projectDeploy.xml" target="addFeatureSet" >
      <property name="pkg" value="../3rdParty/WPF6.1.2/Packages/ExcelBuilders.pkg" />
    </ant>

<!-- add the required featuresets  -->
    <ant antfile="${webcontent.location}/projectDeploy.xml" target="addFeatureSet" >
      <property name="pkg" value="../3rdParty/WPF6.1.2/Packages/Dojo.pkg" />
    </ant>
After the featuresets have been installed, the compile target should be called if any individual developer-contributed source files exist. The task will assume that all source files exist in the WEB-INF/work/source directory. 
<!-- build source files -->
    <ant antfile="${webcontent.location}/projectDeploy.xml" target="compile" />
Before any war files are generated, set the http port on a per-war basis. If you are building Deployment wars to run on separate servers with separate port numbers, then this task will need to be called concurrently with each war file generation. 
<!-- Set the http.port parameter for the Standalone Deployment WAR -->
    <ant antfile="${webcontent.location}/projectDeploy.xml" target="setServerPort" >
      <property name="http.port" value="10000" />
    </ant>
Lastly the generate war task is invoked. Note that the last two steps will be repeated for any additional servers (with differing port numbers), as well as any portlet wars that will be generated. 
<!-- build a production standalone war -->
    <ant antfile="${webcontent.location}/projectDeploy.xml"  
            target="buildDeploymentWar" >
    </ant>

 

build.properties file components

build.properties

The included build.xml sample has an associated build.properties file. This file contains both user modifiable values and a few constants that should not be touched under normal circumstances. Most of the properties in this file resemble the properties of a .bowstreet file found in a project workspace.

buildsrc.location

The root directory of the project in source control. This points to the same directory that the WebContent and .Deployment folders are located. This value must be an absolute path or the build script will fail during war generation.

buildtmp.location

This property defines the working directory for the generation of war files. In the sample this is a temporary directory within the project. In the sample build.xml script this folder is created during the build.

builddist.location

The directory that the generated war files will be placed. In the sample build.xml file this folder is created during the build.

c2a.lib.dir

The directory that contains the ‘pbportlet.jar’ file. This jar is required for building WP native portlet wars and is not shipped with the product. Copy this file from a WebSphere Portal Server installation.

project.name

The name of the project that is being built. This value should be a unique. If you are generating multiple copies of portlet or production war files, this parameter should be passed, with additional unique values, to each subsequent buildDeploymentWar or buildPortletWar Ant invocation.

Note: The following properties are for advanced users and may be left as-is under normal circumstances.

project.location

The project root directory for a build process. This parameter should be identical to buildtmp.location, but is used by external Ant tasks and needs to be defined.

webcontent.location

The WebContent directory for a build process. This parameter should be a subdirectory of the project.location. It is used by an external Ant tasks and needs to be defined.

build.deployment.war.builddir

This property defines the deployment war location for the buildDeploymentWar Ant task. This value is usually defined in the builddist.location property.

wpf.portletwar.location

This is similar to the build.deployment.war.builddir property except it specifies the output directory for generated portlet wars. This value is usually defined in the builddist.location property.

 

Multiple wars in the same project

The included sample build.xml file references a project name defined in the associated build.properties file. If you need to generate multiple factory or portlet wars, in the same project, you will need to pass the project.name parameter, with a new value, in order to avoid overwriting existing war files, since the default project name will be used unless you specify otherwise in the project.name parameter.

Parent topic: Overview: deployment Parent topic: Deployment of a portlet WAR file

Library | Support |