WAS Feature Pack for Modern Batch - Beginners guide to developing Java Batch applications

thingpastoralSoftware and s/w Development

Jul 14, 2012 (4 years and 5 months ago)

797 views



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 1 of 35




WAS Feature Pack for Modern Batch
Beginners guide to developing Java Batch
applications

WP101788

This document can be found on the web at:
www.ibm.com/support/techdocs

Search for document number WP101788 under the category of "TechDocs"
Version 1.5

Author: Edward McCarthy
IBM
edwardmc@au1.ibm.com



Last Updated: 17 January 2011, 09:34



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 2 of 35


Table of Contents
1 OVERVIEW OF THIS GUIDE.........................................................................4
1.1 Introduction.......................................................................................................................................4
1.2 Acknowledgements............................................................................................................................4
1.3 Sample components...........................................................................................................................4
1.3.1 Project Interchange Files.............................................................................................................4
1.3.2 EAR Files....................................................................................................................................4
1.3.3 Other Components.......................................................................................................................5
1.4 Rational Application Developer.......................................................................................................5
1.5 Other required files...........................................................................................................................5
1.5.1 Feature Pack for Modern Batch – jar file.....................................................................................5
2 PROGRAMMING JAVA BATCH APPLICATIONS........................................6
2.1 Introduction.......................................................................................................................................6
2.2 Why a different programming model..............................................................................................6
2.2.1 The coming of Java......................................................................................................................6
2.2.2 Enter Compute Grid.....................................................................................................................7
2.2.3 Contrasting COBOL Batch and Java Batch.................................................................................7
2.2.3.1 COBOL Batch job on z/OS.................................................................................................7
2.2.3.2 Java Batch application in Feature Pack for Modern Batch..................................................7
2.2.4 Developing Java batch applications.............................................................................................8
3 DEVELOPING HELLOWORLD APPLICATION...........................................10
3.1 Introduction.....................................................................................................................................10
3.2 Reference the planned GA package...............................................................................................10
3.3 Building the application..................................................................................................................10
3.3.1 Create Project............................................................................................................................10
3.3.2 Update Build Path......................................................................................................................13
3.3.3 Create HelloBatchWorldStep class............................................................................................14
3.3.3.1 Required methods..............................................................................................................15
3.3.4 Update the generated HelloBatchWorldStep class...................................................................16
3.3.4.1 Add class variable..............................................................................................................16
3.3.4.2 Update getProperties method.............................................................................................16
3.3.4.3 Update processJobStep method.........................................................................................16
3.3.5 Create BatchDataStream class...................................................................................................16
3.3.6 Update the generated HelloBatchWorldBatchDataStream class...............................................18
3.3.6.1 Add class variables............................................................................................................18
3.3.6.2 Update externalizeCheckpointInformation method...........................................................18
3.3.6.3 Update getName method...................................................................................................18
3.3.6.4 Update getProperties method.............................................................................................18
3.3.6.5 Update initialize method....................................................................................................19
3.3.6.6 Update setProperties method.............................................................................................19


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 3 of 35


3.3.7 Add Deployment Descriptors....................................................................................................19
3.3.8 Update ejb-jar.xml.....................................................................................................................20
3.3.8.1 Define resources................................................................................................................23
3.3.9 Update ibm-ejb-jar-bnd.xml......................................................................................................25
3.3.9.1 Add JNDI name for Batch Controller EJB........................................................................25
3.3.9.2 Add JNDI name for Work Manager resource....................................................................26
3.3.10 Export application......................................................................................................................27
3.3.11 Deploy ear file to WAS.............................................................................................................28
3.3.12 Create xJCL...............................................................................................................................29
3.3.13 Run the java batch application...................................................................................................30
3.3.14 Check job result.........................................................................................................................31
3.3.15 Success......................................................................................................................................32
3.4 Properties.........................................................................................................................................33
3.4.1 Step Properties...........................................................................................................................33
3.4.2 BatchDataStream Properties......................................................................................................33
3.4.2.1 Displaying properties set in xJCL......................................................................................33
3.4.3 Prompting for property values at job submission time..............................................................34
3.5 Next steps..........................................................................................................................................35



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 4 of 35



1 Overview of this guide

1.1 Introduction

The techDoc titled ‘IBM Modern Batch - Feature Pack and Compute Grid’ located at

http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101783

provides information about what this new capability for WebSphere Application Server
V7 provides.
The purpose of this techdoc is to step you through developing Java applications that are
run as batch processes in the Feature Pack for Modern Batch.
1.2 Acknowledgements
The author would like to acknowledge the assistance of Chris Vignola and Neeraj Joshi
from WebSphere Compute Grid development in producing this techdoc and the
associated sample code.
1.3 Sample components
The sample provided with this techdoc consists of the following components.
The files described below are available for download from the same location where this
document is downloaded, in a file called:
WP101788-techdoc-Beginners-Guide-attachments.zip
1.3.1 Project Interchange Files
Project Interchange files are zip files that can be imported into Rational Application
Developer V7. These files contain the Java source code used in this sample.
Component Description

wsc-bfp-
helloBatchWorld.zip
Project Interchange file that can be imported in to Rational
Application Developer ( RAD ), contains source code

1.3.2 EAR Files
These EAR files can be deployed into WebSphere Application Server.
Component Description

wsc-bfp-helloWorld2.ear Sample Hello World java batch application



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 5 of 35


1.3.3 Other Components

Component Description

HelloBatchWorldxJCL.xml xJCL xml file used to run the Hello World java batch
application
HelloBatchWorld-
withProps-xJCL.xml
Same as HelloBatchWorldxJCL.xml but with property
elements added

1.4 Rational Application Developer
We used IBM’s Rational Application Developer V7.5.0 to develop our sample
applications.
1.5 Other required files
A jar file from the Feature Pack for Modern Batch was required to develop our
applications.
1.5.1 Feature Pack for Modern Batch – jar file
To develop and run applications that access BFP you need a jar file that is shipped with
the product:
batfepapi.jar
On our system this file were located in this directory:
/shared/wasv7drivers/wcgfep/zWebSphere_OM/V7R0/FPBATCH/lib


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 6 of 35


2 Programming Java Batch applications

2.1 Introduction
In this chapter we discuss the programming model that is used for applications run in the
Feature Pack for Modern Batch.
2.2 Why a different programming model
Since the advent of computing there has been batch processing. Business’s used the
initial computers to run programs in a batch mode. By this we mean the batch process
had an input file of data which the program read through, performing some business
logic on it and writing the data out to a file.
Batch processing is still in wide use today in most businesses, though nearly all would
also have real time systems now as well. Many of the larger customers run their batch
workload on the IBM z/OS operating system, though batch type processing is used on
every platform.
But it is on customer’s z/OS systems that we find large usage batch processing. Often
these run COBOL programs accessing VSAM files or DB2. A batch job may have one or
more steps, where each step runs some different customer program. Note in this
discussion we will refer to COBOL programs, but we are really talking about any
equivalent language e.g. C, Rexx, even shell scrips.
A typical COBOL program when run in a batch job, often will open one or more files,
then loop through each record performing some business logic and writing the updated
record back to the file. Alternatively the batch job may read through every record in a
DB2 table.
On z/OS when a batch job is executed, it is a very quick process for the z/OS operating
system to branch to the COBOL program, taking few instructions.
2.2.1 The coming of Java
The use of Java continues to become more pervasive in many businesses, especially for
applications that handle real time applications. Many customers develop Java
applications that run in IBM’s WebSphere Application Server.
Some customers are already running batch processes that use Java while others are
now starting to consider using Java for batch processes. This is where a key difference
between running a Java program and a COBOL program needs to be understood.
For a batch job to execute a Java program, it is a requirement for a Java Virtual Machine
( JVM ) to be established. Whereas very little CPU is required to invoke a COBOL
program, a significantly larger amount of CPU is required to setup a JVM. Once the JVM
has been setup then the users Java program can be executed.
This might not be an issue if only a few batch jobs were creating JVMs. But customers
have thousands of batch jobs, often with many steps that currently invoke COBOL
programs. If a customer did a straight conversion of these COBOL programs to Java,
then they would see a significant amount of CPU consumed just with the setup and tear
down of numerous JVMs.


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 7 of 35


2.2.2 Enter Compute Grid
z/OS customers are generally very sensitive to how much CPU is used and could well be
concerned with the additional amount of CPU that is going to be incurred by the setup
and shutdown of JVMs.
Additionally, there can be much more setup required to run Java applications in batch.
For example if the batch application wants to perform calls to EJBs in a WebSphere
Application Server, then getting this to work is a complex task. If customers are not
careful, they can end up having to perform a lot of extra work to get their Java batch
applications to work, in effect replicating a lot of the functionality that is provided for real
time applications in a WebSphere Application Server.
This is where the IBM Compute Grid product comes in. It has been available since
around 2008. What it provides is a framework to run batch Java applications in a
WebSphere Application Server like framework.
The Feature Pack for Modern Batch provides at no charge a subset of the Compute Grid
capability in the WAS V7 product.
The techdoc at:
http://techdocs/Don’s-doc-on-why-batch-feature

discusses in more depth why Feature Pack for Modern Batch is seen as the preferred
way for customers to manage and run Java batch applications.
To run batch applications in the Feature Pack for Modern Batch means that they need to
be written in a way that fits into the framework provided.
2.2.3 Contrasting COBOL Batch and Java Batch
If you’re new to Java then it may help to contrast the setup for a typical COBOL batch
job on z/OS and running a Java batch application in the Feature Pack for Modern Batch.
2.2.3.1 COBOL Batch job on z/OS
For a batch job running on z/OS, a developer would have written a COBOL program and
then compiled it. The compilation process creates a load module which is stored in a
dataset.
Then they create JCL and store that in a dataset as well.
Then the JCL is submitted creating a batch job. z/OS executes the batch job. z/OS
needs to link to the specified COBOL program, to do that it loads into memory from the
dataset it was stored in. Once loaded in memory, z/OS can link to the COBOL program
and it can start running.
This is an over simplification to some extent, but that is the essence of what happens.
2.2.3.2 Java Batch application in Feature Pack for Modern Batch
To run an application as a batch process in the Feature Pack for Modern Batch, a
developer needs to develop their Java application which needs to implement certain
interfaces, more on this shortly.
Once the application has been developed, it is packaged into an EAR file. It is then
deployed into the WebSphere environment that has the Feature Pack for Modern Batch.


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 8 of 35


A mechanism in then required to run the deployed application as a batch process. This
is done by using an Extensible Markup Language XML dialect called XML xJCL Job
Control Language.
An xml file is created containing xJCL. The xJCL is akin to z/OS JCL. It defines what
steps there are to run, references to input and output data sources, and the name of the
deployed application to run. This xml file is then submitted to the WebSphere
environment where it will be actioned, the result being that the application is run in a
batch fashion.
2.2.4 Developing Java batch applications
As mentioned for your application to run in the Feature Pack for Modern Batch capability
of WebSphere V7, it needs to be written in a certain way.
The article titled: Introduction to batch programming using WebSphere Extended
Deployment Compute Grid at this link:
http://www.ibm.com/developerworks/websphere/techjournal/0801_vignola/0801_
vignola.html

provides a detailed description of what is required to develop a Java batch application.
Chapter 3 of this techdoc will step you through creating a hello world Java batch
example.
Your Java batch application will have a class that must implement the
BatchJobStepInterface. This requires that the class implements a number of methods.
The following table describes these methods:
Method Returns Description

createJobStep void Called by the Batch Container
destroyJobStep int Called when the Batch Container has
finished processing the job step, any
clean up code can be added here
getProperties java.util.Properties

Returns the properties specified in
xJCLfor the batch job step
processJobStep int Contains all the business logic for the
batch job step
setProperties void Called by the Batch Container to
make the properties specified in xJCL
available to the batch job step

This link titled ‘Batch Job Steps’ from the WAS Feature Pack for Modern Batch
infocenter describes in more detail the above methods:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/index.jsp?topic=/com.ibm.we
bsphere.bpfep.multiplatform.doc/info/ae/ae/cgrid_xdbatchstp.html




© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 9 of 35


If your new to Java, you may not be familiar with the concept of interfaces. In brief when
the xJCL xml file is executed by WebSphere, the Feature Pack for Modern Batch Java
code is going to invoke the above methods on the class you have specified in the xJCL.
It is this interface technology that makes this all work.




© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 10 of 35


3 Developing HelloWorld application

3.1 Introduction
In this chapter we describe how to develop a HelloWorld Java batch application. Typical
of HelloWorld examples this application does not do anything apart from write some
messages to the WAS system log. It is however a good starting point because it shows
the required Java code that is required to develop any Java batch application regardless
of complexity.
3.2 Reference the planned GA package
When developing java code to work with Feature Pack for Modern Batch you will need to
add import statements and interfaces that reference the Feature Pack for Modern Batch.
In the Beta release there are two packages that have the same classes. If you are using
RAD, it will show you both as choices to use. The packages are called
com.ibm.websphere.batch and com.ibm.batch.api.
The com.ibm.batch package will be removed for the GA release.
You should only use the com.ibm.websphere.batch packages in your code.
In any examples in this techdoc we always used the com.ibm.websphere.batch package.
3.3 Building the application
We used IBM Rational Application Developer ( RAD ) V7.5 to develop the sample code
supplied with this techdoc. If you do not use RAD as your Java development
environment, don’t stop reading. This part of the techdoc will still provide you with
relevant details about how to develop Java batch applications using what ever Java
development mechanism you use.
3.3.1 Create Project
In RAD create a new project by selecting File -> New -> Enterprise Application Project
as shown below:

In the window displayed set the Project Name to BatchFeaturePackSampleApps as
shown below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 11 of 35




Click Next and a window titled ‘New EAR Application Project’ appears, click on the ‘New
Module’ button. This displays a new window titled ‘Create default Java EE Modules’. In
that display select only the one for ‘EJB module’ as shown below:



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 12 of 35



Click Finish to return to the ‘New EAR Application Project’ window and click Finish in that
window as well. Your project will then be generated by RAD and appear similar to the
display below:




© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 13 of 35


3.3.2 Update Build Path
The build path for the project needs to be updated to include jar files from the Feature
Pack for Modern Batch. This needs to be done to make the Java classes and APIs of
the Feature Pack for Modern Batch available to the Java code you will be developing.
Right click on BatchFeaturePackSampleAppsEJB and select Build Path -> Configure
Build Path… as shown below:


RAD will display a window titled ‘Properties for BatchFeaturePackSampleAppEJB, click
on the Libraries tab and then the ‘Add External JARs’ button which will bring a File dialog
box as shown below:


You need to locate the batfepapi.jar file. The updated display will then look similar to
this:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 14 of 35





Click OK to save the change.
3.3.3 Create HelloBatchWorldStep class
Even though we selected the EJB Module option when we created the project we will not
be developing any EJBs in this example. What we do need to create is a class that is
going to be our Java batch application.
In RAD right click on ejbModule and select New -> Class as shown below:



RAD displays a new Window called ‘New Java Class’. Set the package name to
com.ibm.wsc.bfpSample and the Name to HelloBatchWorldStep as shown below. Then
click on the Add button which will display a window called ‘Implemented Interfaces
Selection, in this display type in the name BatchJobStepInterface. As you type this in
RAD will update the display with matching items, select the interface from the
com.ibm.websphere.batch package as shown below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 15 of 35





Click OK to add and save the interface change then cancel to close that window, then
click Finish and RAD will create the class. RAD will open for edit the new Java class as
shown below:

3.3.3.1 Required methods
The BatchJobStepInterface requires that the class implements a number of methods and
these are automatically generated for you by RAD. The following table describes these
methods:
Method Returns Description

createJobStep void Called by the Batch Container


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 16 of 35


destroyJobStep int Called when the Batch Container has
finished processing the job step, any
clean up code can be added here
getProperties java.util.Properties

Returns the properties specified in
xJCLfor the batch job step
processJobStep int Contains all the business logic for the
batch job step
setProperties void Called by the Batch Container to
make the properties specified in xJCL
available to the batch job step

This link titled ‘Batch Job Steps’ from WAS Feature Pack for Modern Batch describes
these methods:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/index.jsp?topic=/com.ibm.we
bsphere.bpfep.multiplatform.doc/info/ae/ae/cgrid_xdbatchstp.html

3.3.4 Update the generated HelloBatchWorldStep class
To make a valid java batch application the generated HelloBatchWorldStep java class
needs to have a few changes made to it.
3.3.4.1 Add class variable
Add the following lines to define a class variable:
Properties props = new Properties();
3.3.4.2 Update getProperties method
The generated code for this method contains this return statement:
return null
A null value will cause an exception if you try to run the class as a java batch job. An
object of type Properties must be returned by this method.
We modified the return statement on the method to be this:
return props;
3.3.4.3 Update processJobStep method
The processJobStep method is where the business logic for the application is coded. As
our aim it to show how to develop a hello world example, we added this line so that
when our java batch application has been successfully executed we will see evidence of
this is the system out log file:
System.out.println("One small step for Java, one giant leap for batch");
3.3.5 Create BatchDataStream class
A real world Java batch application will have business logic much like a traditional batch


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 17 of 35


application. A typical batch application will read data from one source, perform some
business logic and then write the updated logic to a target.
A COBOL batch application run on z/OS uses a DD statement to associate a logical file
reference in the COBOL code to an actual file.
The BatchDataStream concept performs this same task for a java application using the
Feature Pack for Modern Batch.
In the GA release it will be possible to develop a java batch application that does not
require any BatchDataStream classes. At the time of the Beta release however a
minimum of one of these classes is required otherwise an exception will be generated
the job is processed.
For the purposes of this Hello World type example, the java class we developed to be
used for the batch data stream does not do anything. However understanding the use of
the batch data stream concept is key to using the Feature pack for Modern Batch.
Sources of information about the batch data stream can be found in the infocenter and
also in the article at:
http://www.ibm.com/developerworks/websphere/techjournal/0801_vignola/0801_
vignola.html

It is also suggest that reviewing the supplied sample XDCGIVT ear file.
To create the required class, in RAD right click on com.ibm.wsc.bfpSample and select
New -> Class as shown below:


RAD displays a new Window called ‘New Java Class’. The package name will already
be set to com.ibm.wsc.bfpSample, set the Name to HelloBatchWorldBatchDataStream
as shown below. Then click on the Add button which will display a window called
‘Implemented Interfaces Selection, in this display type in the name BatchDataStream.
As you type this in RAD will update the display with matching items, select the interface
from the com.ibm.websphere.batch package as shown below:



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 18 of 35





Click OK to add and save the interface change then cancel to close that window, then
click Finish and RAD will create the class with the required methods. RAD will open for
edit the new Java class.
3.3.6 Update the generated HelloBatchWorldBatchDataStream class
A few minor changes are required to the generated HelloBatchWorldBatchDataStream to
avoid runtime exceptions.
3.3.6.1 Add class variables
Add the following lines to define two class variables:
String logicalName = null;
Properties props = new Properties();
3.3.6.2 Update externalizeCheckpointInformation method
Set the last line of the externalizeCheckpointInformation method to:
return "1";
3.3.6.3 Update getName method
Set the last line of the getName method to:
return this.logicalName;
3.3.6.4 Update getProperties method
Set the last line of the getProperties method to:
return props


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 19 of 35


3.3.6.5 Update initialize method
Set the last line of the initialize method to:
logicalName = arg0;
3.3.6.6 Update setProperties method
Set the last line of the setProperties method to:
props = arg0

3.3.7 Add Deployment Descriptors
When we created our project we took the default of 5.0 for the EAR version. A
consequence of this is that no deployment descriptor is automatically generated as part
of the project. In this version of EARs deployment descriptors are optional as there are
new ways to handle the functionality that the deployment descriptors used to provide.
In our case however we still wanted to use the Deployment Descriptor approach so we
need to add one back into the project. To do this right click on
BatchFeaturePackSampleAppsEJB and select Java EE -> Generate Deployment
Descriptor Stub as shown below:


RAD will create a file called ejb-jar.xml under the ejbModule folder.
We also wanted to add the ibm-ejb-jar-bnd.xml file to our project. This file is an IBM
extension which is used to store the actual JNDI name of resources. In an application
that has defined logical resources, when the application is deployed into WAS, you need
to map these logical resources to the JNDI name of an actual resource defined in WAS.
If you know what the actual JNDI name is going to be, then you can store that value in
this file, which means that you do not have to manually do this mapping when you
deploy the application into WAS. To create this file use the same approach as above
but select ‘Generate WebSphere Bindings Deployment Descriptor.
The two files will appear in RAD similar to the display below:



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 20 of 35



3.3.8 Update ejb-jar.xml
The ejb-jar.xml file is used to specify information that helps to connect your java
application to the Java application server it runs in which in our case is WebSphere
Application Server ( WAS ).
For Java batch applications you need to define a reference to what is called a ‘Controller
Bean’ in the ejb-jar.xml file. This is explained in the WAS Feature Pack for Modern
Batch V7 Infocenter in an article title ‘Batch Controller Bean’ at this link:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/index.jsp?topic=/com.ibm.we
bsphere.bpfep.multiplatform.doc/info/ae/ae/cgrid_xdbatchcb.html

As this link explains, even though you define a reference to this ‘Controller Bean’ in the
ejb-jar.xml file of your application, your application does not contain the actual class for
the ‘Controller Bean’. Rather when you deploy your application into WAS, WebSphere
detects this reference to the ‘Controller Bean’ and automatically creates a class to be
used by the Feature Pack for Modern Batch for your application.
The other benefit of this approach as also described in the above link, is that code in the
batch data stream class can lookup resources defined in the ejb-jar.xml file via the
java:comp/env convention.
Select EJB Project (BatchFeaturePackSampleAppsEJB) then click the Add button, in the
‘Add Item’ window displayed select ‘Enterprise Beans’ and click Ok as shown below:



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 21 of 35



Select ‘Enterprise Beans’ and then click the Add button, in the Add Item window select
‘Session Bean’ and click ok as shown below:


This will display a small window, set the ‘EJB name’ field to a value of your choice, in our
case we used the value BatchController, and set the Description field as shown below
then click Ok:




© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 22 of 35


The display in the ejb-jar.xml will then be updated accordingly and look similar to below:



There are a number of fields that need to be set for the EJB session bean you have just
added. In the ‘Bean Type’ field select Stateless from the drop down box. In the
‘TransactionType’ field select ‘Container Manager’ from the drop down box. Then click
on the Browse button for the EJB Class field. This will display a window called ‘Type
Selection, type in BatchJobController. As you type this in RAD will update the display
with matching items, select the class called BatchJobControllerBean as shown below:




© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 23 of 35



Use a similar process to set the Home interface to
com.ibm.ws.batch.BatchJobControllerHome and the Remote interface to
com.ibm.ws.batch.BatchJobController.
3.3.8.1 Define resources
Under the covers, the Batch Feature is using asynchronous beans in WAS to run the
Java batch applications. There are two types of asynchronous beans that can be
defined in WAS called ‘Timer managers’ and ‘Work Managers’.
When the WAS environment is augmented with the Feature Pack for Modern Batch a
new ‘Work Manager’ resource is defined called BatchWorkManager as shown below:



You need to define a reference to this resource in the ejb-jar.xml file.
Select the ‘Session Bean’ then right click, select Add -> Resource Reference as shown
below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 24 of 35




RAD will display a window titled ‘Add Resource Reference’. Set Name to
BatchWorkManager, type to commonj.work.WorkManager, Authentication to Container
and ‘Sharing Scope’ to Shareable as shown below:


Click Finish and the ejb-jar.xml file will be updated with the new definition.
Save the updated xml file.


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 25 of 35


3.3.9 Update ibm-ejb-jar-bnd.xml
In the previous section we added a logical resource to represent the Work Manager
resource in WAS. When the application is deployed into WAS, this logical resource has
to be bound to an actual defined resource. During deployment this is done by selecting
the JNDI name of the resource you want to bind the logical resource to.
If you know in advance what this JNDI name will be you can set it in the ibm-ejb-jar.xml
file.
Double click on the ibm-ejb-jar-bnd.xml file to open it for editing. We need to add two
entries, one for the Batch Controller EJB reference and one for the Work Manager
resource.
3.3.9.1 Add JNDI name for Batch Controller EJB

Click the Add button which will bring up a window called ‘Add Item’. Select Session and
click Ok as shown below:


RAD will add a Session entry. Next we need to find the EJB reference we want to add
the JNDI name for. Click on the Browse button which will display a window titled ‘Select
Session Bean’. Select BatchController and click OK as shown below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 26 of 35




RAD will update the xml file. Set the ‘Simple Binding Name’ field to
ejb/com/ibm/wsc/bfpSample/BatchController.
Note this JNDI name needs to be unique within the WAS cell. You need to use a
different name for different Java batch applications.
3.3.9.2 Add JNDI name for Work Manager resource
Select the Session EJB then click on the Add button, in the window titled ‘Add Item’
select ‘Resource Reference’ as shown below:


Then click Ok. Set the Name and ‘Binding Name’ fields to wm/BatchWorkManager as
shown below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 27 of 35




Save the changes to the file.
3.3.10 Export application
The application can now be exported to an ear file. In RAD select the
BatchFeaturePackSampleApps project, right click and select Export -> Ear File as
shown below:

This will bring up a Window titled Export as shown below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 28 of 35




Use the Browse button to select the directory to save the ear file to and click Finish.
3.3.11 Deploy ear file to WAS
Deployment of the ear file into WAS is the normal procedure. The only requirement is
that the target server or cluster you intend to deploy the ear file into must have been
configured as a WebSphere grid endpoint.
You can determine valid servers or clusters by using the WAS Admin GUI, select
System Administration -> Job Scheduler as shown below to see settings associated with
the Feature Pack for Modern Batch:

Clicking on ‘WebSphere grid endpoints’ will show the defined servers and/or clusters in


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 29 of 35


your cell, similar the display below:


If you are using a stand alone server then all Batch Feature components are in the one
server in which case there is no decision.
3.3.12 Create xJCL
To have the Feature Pack for Modern Batch run your application as batch job you need
to setup what is called an xJCL XML file.
The xJCL XML file to run this Hello World sample is supplied with this techdoc.
The way we created it was to take a supplied sample and then modify it to suit our
application.
On a distributed system, a WAS installation that has been augmented with the Feature
Pack for Modern Batch will have a directory called ‘longRunning’ which contains sample
xJCL files.
We used the XDCGIVTbyte2bytexJCL.xml to create the HelloBatchWorldxJCL.xml file to
run our application.
The picture below is taken from a display of the HelloBatchWorldxJCL.xml in a Mozila
Firefox browser.


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 30 of 35



There are a lot of parts in the above diagram, but the aim is to try and show how values
in the xJCL XML file relate to various parts of what we have used to develop the
application and the WAS environment we use to run the application.
The following described the numbered parts of the above display:
1. The name of the java batch job, the value used here is what will appear in
the Job Management Console when the ‘View Jobs’ link is used
2. The value set as the ‘default application name’ must match the name the
application was deployed as in the WAS cell
3. The job-step element represents a step in the job, in this case the job only
has one step called HelloBatchWorldStep, this can be any value that you
require
4. The classname element in the job-step element corresponds to the class
we developed in RAD which contains the business logic, the impl-class
element corresponds to the class we developed in RAD that handles the
batch stream functionality
5. Each step must have a checkpoint-algorithm-ref element that refers to a
defined checkpoint-algorithm element
3.3.13 Run the java batch application
Having deployed our java batch application into the WAS cell and created our xJCL we
can now use the Job Management Console to submit the xJCL.
In a browser access the Job Management Console ( JMC ) by entering a URL of the
5
1
2
3
4


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 31 of 35


form
https://localhost:9446/jmc/console.jsp

Enter a valid userid and password to logon. In the JMC click on the ‘Submit a job’ link as
shown below:


Click on the browse button to locate the HelloBatchWorldxJCL.xml file and then click
Submit. The job will be submitted and the display updated with something similar to the
following:


Note how a unique job number has been appended to the job name.
3.3.14 Check job result
We then used the Job Management Console to check the processing of the job we have
submitted. Click on the ‘View Jobs’ link and a display showing the status of batch jobs
submitted is shown, similar to below:


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 32 of 35




Clicking on the HelloBatchWorldStep:00072 link will bring up a display showing
information related to the running of the job, part of the initial display is shown below:



Here is another part of the output in which you can see the message we added to the
processJobStep method:

3.3.15 Success
We have now completed showing how to develop, deploy and run our Hello World java
batch example.


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 33 of 35


3.4 Properties
It is to be expected that a real world java batch application will need properties passed to
it and there is a standard way to achieve that in the Feature Patch for Modern Batch.
3.4.1 Step Properties
To pass properties to the application class run in a step a props type of element can be
added to the job-step element. Below shows the HelloBatchWorldxJCL.xml we used
previously but with a props element added:

<job-step name="HelloBatchWorldStep">
<classname>com.ibm.wsc.bfpSample.HelloBatchWorldStep</classname>
<checkpoint-algorithm-ref name="chkpt" />
<batch-data-streams>
<bds>
<logical-name>outputStream</logical-name>
<impl-class>
com.ibm.wsc.bfpSample.HelloBatchWorldBatchDataStream
</impl-class>
</bds>
</batch-data-streams>
<props>
<prop name="step-1-prop-1" value="value for step 1 prop 1" />
<prop name="step-1-prop-2" value="value for step 1 prop 2" />
</props>
</job-step>
Any number of prop elements can be defined within a props element.
3.4.2 BatchDataStream Properties
Properties can also be passed to the class that is used for the batch data stream in a
step. Below shows the above HelloBatchWorldxJCL.xml with a props element added to
the batch-data-stream element:

<job-step name="HelloBatchWorldStep">
<classname>com.ibm.wsc.bfpSample.HelloBatchWorldStep</classname>
<checkpoint-algorithm-ref name="chkpt" />
<batch-data-streams>
<bds>
<logical-name>outputStream</logical-name>
<impl-class>
com.ibm.wsc.bfpSample.HelloBatchWorldBatchDataStream
</impl-class>
<props>
<prop name="bds-1-prop-1" value="value for bds 1 prop 1" />
<prop name="bds-1-prop-2" value="value for bds 1 prop 2" />
</props>
</bds>
</batch-data-streams>
<props>
<prop name="step-1-prop-1" value="value for step 1 prop 1" />
<prop name="step-1-prop-2" value="value for step 1 prop 2" />
</props>
</job-step>
Any number of prop elements can be defined within a props element.
3.4.2.1 Displaying properties set in xJCL
We added some code to the setProperties method in both classes in our


© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 34 of 35


HelloBatchWorld example so that it would display all properties in the properties object
passed in, the output is shown below:

[20/07/10 23:33:57:687 EST] 00000027 SystemOut O HelloBatchWorldBatchDataStream: in
setProperties: props size: 3
[20/07/10 23:33:57:687 EST] 00000027 SystemOut O ii: 1 prop: name: bds-1-prop-2 value: value for
bds 1 prop 2
[20/07/10 23:33:57:687 EST] 00000027 SystemOut O ii: 2 prop: name: bds-1-prop-1 value: value for
bds 1 prop 1
[20/07/10 23:33:57:687 EST] 00000027 SystemOut O ii: 3 prop: name: IS_JOB_RESTART value: false
[20/07/10 23:33:57:687 EST] 00000027 impl I CWLRB5618I: [07/20/10 23:33:57:687 EST]
Initializing step HelloBatchWorldStep batch data stream outputStream
[20/07/10 23:33:57:687 EST] 00000027 impl I CWLRB5620I: [07/20/10 23:33:57:687 EST]
Opening step HelloBatchWorldStep batch data stream outputStream
[20/07/10 23:33:57:703 EST] 00000027 impl I CWLRB5622I: [07/20/10 23:33:57:703 EST]
Loading job step bean for step HelloBatchWorldStep using class name:
com.ibm.wsc.bfpSample.HelloBatchWorldStep
[20/07/10 23:33:57:718 EST] 00000027 SystemOut O HelloBatchWorldStep: in setProperties: props
size: 4
[20/07/10 23:33:57:718 EST] 00000027 SystemOut O ii: 1 prop: name:
com.ibm.websphere.batch.StepID value: HelloBatchWorldStep
[20/07/10 23:33:57:718 EST] 00000027 SystemOut O ii: 2 prop: name: step-1-prop-2 value: value for
step 1 prop 2
[20/07/10 23:33:57:718 EST] 00000027 SystemOut O ii: 3 prop: name: step-1-prop-1 value: value for
step 1 prop 1
[20/07/10 23:33:57:734 EST] 00000027 SystemOut O ii: 4 prop: name: com.ibm.websphere.batch.JobID
value: HelloBatchWorldStep:00090
3.4.3 Prompting for property values at job submission time
If you code a property in this fashion: <prop name="FILENAME" value="${inputDataStream}" />
When xJCL is submitted using the Job Management Console, the presence of a property
value with the syntax ${<name>} will cause it to display a screen where you can enter a
value for that property. Shown below is a sample of where an xJCL XML file has been
submitted and a number of properties require a value to be supplied:



© 2010, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/17/2011

http://www.ibm.com/support/Techdocs

WP101788 Beginners Guide to Coding Java Batch Jobs Page 35 of 35



3.5 Next steps
Hopefully after reading the above you now have a better understanding of how to get
started on developing and running Java batch applications.
It is recommended that you have a look at the code in the supplied sample applications
as they demonstrate some of the capabilities that exist in the Feature Pack for Modern
Batch.
You can then start developing your own java batch applications.