Building J2C Java beans using Ant scripts

You can use Ant scripts to invoke J2C components, and these Ant scripts can be called from the workbench or from the command line.

There are some situations where you may want to recreate the J2C Java™ beans and/or Data binding beans (for example, if your COBOL copybook adds a new field). This can now be achieved by using an Ant definition file which mimics the interaction between the user and the underlying J2C components.

The J2C wizards allow you to quickly create an Ant configuration file by capturing your selections and entered values. Since an Ant configuration file is in essence an XML file, it can be modified or built entirely by hand.

An Ant configuration file consists of a target tree where various tasks are run. Tasks within a target are processed in a pipeline fashion. Each task is run by an object that implements a particular task interface. When the Ant configuration file is invoked, properties corresponding to each task are loaded into the implementing task objects. Once the information is loaded the task object is invoked.

Data Discovery Task

In general, there are two steps involved during an discovery cycle, each of which is done by a distinct component:

• Discovery agents perform the actual import of data (see performImport task in the example script) to produce proprietary metadata which are called import result.
• Resource writers consume the import result (see writeToWorkspace task in the example script) to produce appropriate application artifacts.

During the import and generation steps, the Discovery Agent and the Resource Writer require a set of user input to be provided. For example, in the Query phase, each Discovery Agent will have a different set of parameters that are used to define a query on the corresponding metadata repository. The Discovery Agent and the Resource Writer can be paired a various ways to import and generate the desired artifact. They are identified by their name (QName). For example, the Cobol Discovery Agent can by identified by the following name: {com/ibm/adapter}CobolDiscoveryAgent

The following script example shows how to generate the J2C java interface, J2C java implementation as well as the data binding classes based on the taderc99.cbl COBOL file and importing the ECIResourceAdapter version 6.0.2.

<adapter:discover>
	<adapter:performImport agent="{com/ibm/adapter}CobolDiscoveryAgent">
		<adapter:importResource>
			<adapter:propertyGroup name="CobolFileGroup">
				<adapter:propertyElement name="CobolFile" value="/${project}/taderc99.ccp"/>
			</adapter:propertyGroup>
		</adapter:importResource>
		<adapter:queryProperties>
			<adapter:propertyGroup name="ImportProperties">
				<adapter:propertyElement name="Platform" value="Win32"/>
			</adapter:propertyGroup>
		</adapter:queryProperties>
		<adapter:queryResult>
			<adapter:selectElement name="DFHCOMMAREA"/>
		</adapter:queryResult>
	</adapter:performImport>
	<adapter:writeToWorkspace writer="{com/ibm/adapter/cobol/writer}JAVA_WRITER">
		<adapter:propertyGroup name="COBOLToJavaResourceWriter">
			<adapter:propertyElement name="GenerationStyle" value="0"/>
			<adapter:propertyGroup name="Java Type Name">
				<adapter:propertyElement name="Overwrite existing class" value="true"/>
				<adapter:propertyElement name="Project Name" value="${project}"/>
				<adapter:propertyElement name="Package Name" value="com.ibm.test"/>
				<adapter:propertyElement name="Class Name" value="Taderc99"/>
			</adapter:propertyGroup>
		</adapter:propertyGroup>
	</adapter:writeToWorkspace>
</adapter:discover>

The Import section of the Ant script looks like this:
```
<discoveryAgent type="DiscoveryAgentName">
		<importResource name="PropertyName" value="PropertyValue"/>
		<importProperties>
			<propertyElement name="PropetyName" value="PropertyValue"/>
		</importProperties>
		<searchParameters>
			<propertyElement name="ParameterName"/>
		</searchParameters>
</discoveryAgent>
```
Where:
- discoveryAgent is the name of the Discovery agent to be used for import
- importResource is the resource to be imported
- queryProperties is a list of parameters that represent the information required to form a query against the metadata repository
- searchParameters is the select nodes on the result tree that are desired for import as application artifacts
- propertyElement is a list (pairs of property name and property value)
In order to generate the application artifact, a Resource Writer that knows to consume the imported result is invoked. For instance, after an import of type COBOL only a writer that knows to consume the COBOL type Import Result can be used. The Write section of the Ant script looks like this:
```
<adapter:writeToWorkspace writer="{com/ibm/adapter/cobol/writer}JAVA_WRITER">
<adapter:propertyGroup name="COBOLToJavaResourceWriter">
<adapter:propertyGroup name="Java Type Name">
<adapter:propertyElement name="Project Name" value="${project1}"/>
<adapter:propertyElement name="Package Name" value="sample.cics"/>
<adapter:propertyElement name="Class Name" value="DFHCOMMAREA"/>
</adapter:propertyGroup>
</adapter:propertyGroup>
</adapter:writeToWorkspace>
```
Where:
- workspaceResourceWriter is the name of the writer used to generated the application artifacts
- propertyElement is a list (pairs of property name and property value) that the writer uses for generation

In the special case of the language import (COBOL, C and PL/I) there is an additional step, which is Binding generation. The Binding section of the Ant script looks like this:

<createBinding package="PackageName" class="ClassName">
    <methodElement>
        <name value="MethodName"/>
        <input value="Input"/>
        <output value="Output"/>
        <interactioSpec>
            <propertyElement name="PropertyName" value="PropetyValue"/>
        </interactioSpec>
    </methodElement>
    <connectionSpec>
        <propertyElement name="PropertyName" value="PropertyValue"/>
    </connectionSpec>
    <resourceAdapter project="ResourceAdapterProjectName"/>
</createBinding>

The resourceAdapter can also be defined in the following way:
```
<resourceAdapter>
     <propertyElement name="displayName" value="PropertyValue"/>
     <propertyElement name="version" value="PropertyValue"/>
     <propertyElement name="vendorName" value="PropertyValue"/>
</resourceAdapter>
```
Where:
- createBinding defines the package and interface binding class name
- methodElement is the Java method to access the EIS
  - name is the name of the method
  - input is the input type
  - output is the output type
  - interactioSpec is a list of interaction properties
- connectionSpec is a list of connection properties
- resourceAdapter is the Resource Adapter used either by specifying the project name or a list of properties
Once properties are set it is time to run a command that invokes the underlying API to drive either the import or the artifacts generation.

Note: Keep these guidelines in mind while using your Ant scripts:

If you are calling a resource adapter in your Ant script, the resource adapter must be imported in the workspace before invoking the Ant script.
Any resource used must have either a file path that points to the workspace and project, or a full file system path.
Discovery Agents and Workspace Writer are referred by their name (QName) which is uniquely identified. To find all registered Discovery Agents, Workspace Resource Writers, and Import configurations, use the displayAll.xml script found in the script directory.
Some of the elements have a pair of name, value attributes. The name is actually a property defined internally by the Discovery Agent or Resource Writer and it is used to pass the value along. It is important to get the name right. If the name is not recognized by the component the value will not be set. In all the cases these attributes are part of a propertyElement tag which has a one-to-many multiplicity. The same multiplicity also applies to the methodElement tag.

The following script example generates a data binding based on the specified (taderc99.ccp) COBOL file. The script can be found in the com.ibm.adapter.command plugin, script directory.

<?xml version="1.0" encoding="UTF-8" ?> 
  <project xmlns:adapter="http://com.ibm.adapter" default="DataBinding1" name="/Taderc99/CustomerInfo.xml">
    <property name="debug" value="true" /> 
    <property name="project1" value="Taderc99" /> 
    <target name="DataBinding1">
  <adapter:createProject projectName="${project1}" projectType="Java" /> 
    <adapter:discover>
    <adapter:performImport agent="{com/ibm/adapter}CobolDiscoveryAgent">
    <adapter:importResource>
    <adapter:propertyGroup name="CobolFileGroup">
  <adapter:propertyElement name="CobolFile" value="C:\Samples\CICS\taderc99\taderc99.cbl" /> 
  </adapter:propertyGroup>
  </adapter:importResource>
    <adapter:queryProperties>
    <adapter:propertyGroup name="ImportProperties">
  <adapter:propertyElement name="Platform" value="Win32" /> 
  <adapter:propertyElement name="Codepage" value="ISO-8859-1" /> 
  <adapter:propertyElement name="Numproc" value="PFD" /> 
  <adapter:propertyElement name="FloatingPointFormat" value="IEEE 754" /> 
    <adapter:propertyGroup name="ExternalDecimalSignGroup">
  <adapter:propertyElement name="ExternalDecimalSign" value="ASCII" /> 
  </adapter:propertyGroup>
    <adapter:propertyGroup name="EndianGroup">
  <adapter:propertyElement name="Endian" value="Little" /> 
  <adapter:propertyElement name="RemoteEndian" value="Little" /> 
  </adapter:propertyGroup>
    <adapter:propertyGroup name="CompileOptions">
  <adapter:propertyElement name="Quote" value="DOUBLE" /> 
  <adapter:propertyElement name="Trunc" value="STD" /> 
  <adapter:propertyElement name="Nsymbol" value="DBCS" /> 
  </adapter:propertyGroup>
  </adapter:propertyGroup>
  </adapter:queryProperties>
    <adapter:queryResult>
  <adapter:selectElement name="DFHCOMMAREA" /> 
  </adapter:queryResult>
  </adapter:performImport>
    <adapter:writeToWorkspace writer="{com/ibm/adapter/cobol/writer}JAVA_WRITER">
    <adapter:propertyGroup name="COBOLToJavaResourceWriter">
  <adapter:propertyElement name="GenerationStyle" value="Default" /> 
    <adapter:propertyGroup name="Java Type Name">
  <adapter:propertyElement name="Project Name" value="${project1}" /> 
  <adapter:propertyElement name="Package Name" value="sample.cics" /> 
  <adapter:propertyElement name="Class Name" value="CustomerInfo" /> 
  <adapter:propertyElement name="Overwrite existing class" value="true" /> 
  </adapter:propertyGroup>
  </adapter:propertyGroup>
  </adapter:writeToWorkspace>
  </adapter:discover>
  <eclipse.refreshLocal depth="infinite" resource="${project1}" /> 
  <eclipse.incrementalBuild project="${project1}" /> 
  </target>
  </project>

Where:

• importResource defines the resource to be imported
• queryProperties are the parameters that represent the information required to form a query against the metadata repository
managedConnectionFactory defines the connection factory properties
• queryResult are the selected nodes on the result tree that are desired for import as application artifacts
• propertyGroup is the structure containing the properties and their values.

Service Generation Task

In the special case of the language import (COBOL, C and PL/1), there is an additional step that involves the Interface Binding generation. The following example describes the data discovery section of the Ant script used for J2C Bean generation:

<j2c:generateService>
	<j2c:buildService package="com.ibm.test" class="Taderc99Interface">
		<j2c:method>
			<j2c:methodName value="gettaderc99"/>
			<j2c:methodInput value="${project}/com/ibm/test/Taderc99.java">
				<j2c:argumentBinding property="commareaLength" propertyType="InteractionSpec" name="length" type="int"/>
			</j2c:methodInput>
			<j2c:methodOutput value="${project}/com/ibm/test/Taderc99.java"/>
			<j2c:interactionSpec class="com.ibm.connector2.cics.ECIInteractionSpec">
				<adapter:propertyGroup name="InteractionSpec property group">
					<adapter:propertyElement name="functionName" value="TADERC99"/>
				</adapter:propertyGroup>
			</j2c:interactionSpec>
		</j2c:method>
		<j2c:managedConnectionFactory class="com.ibm.connector2.cics.ECIManagedConnectionFactory" target="myJNDIName">
			<adapter:propertyGroup name="Managed connection property group">
				<adapter:propertyGroup name="Server">
					<adapter:propertyElement name="ConnectionURL" value="rubicon.torolab.ibm.com"/>
					<adapter:propertyElement name="ServerName" value="rubicon"/>
				</adapter:propertyGroup>
				<adapter:propertyGroup name="UserVerification">
					<adapter:propertyElement name="UserName" value="sysad"/>
					<adapter:propertyElement name="Password" value="sysad"/>
				</adapter:propertyGroup>
			</adapter:propertyGroup>
		</j2c:managedConnectionFactory>
		<j2c:connectionSpec class="com.ibm.connector2.cics.ECIConnectionSpec"/>
		<j2c:resourceAdapter project="CICS ECI"/>
	</j2c:buildService>
	<adapter:writeToWorkspace writer="com/ibm/adapter/j2c/codegen:J2CAnnotationWriter">
		<adapter:propertyGroup name="J2C Writer Properties">
			<adapter:propertyElement name="Project" value="${project}"/>
			<adapter:propertyElement name="InterfaceName" value="Taderc99Interface"/>
			<adapter:propertyElement name="BindingName" value="Taderc99Binding"/>
			<adapter:propertyElement name="PackageName" value="com.ibm.test"/>
			<adapter:propertyGroup name="CommandBean">
				<adapter:propertyGroup name="gettaderc99">
					<adapter:propertyElement name="EnableGenerate" value="true"/>
					<adapter:propertyElement name="CommandBeanName" value="Taderc99CICSECIServiceProxy"/>
					<adapter:propertyElement name="Input" value="Taderc99Part"/>
					<adapter:propertyElement name="Output" value="Taderc99Part"/>
				</adapter:propertyGroup>
			</adapter:propertyGroup>
		</adapter:propertyGroup>
    </adapter:writeToWorkspace>
</j2c:generateService>

Where:

buildService defines the package and interface binding class name
method is the Java™ method to access the EIS
- methodName is the name of the method
- methodInput is the input type
- methodOutput is the output type
- interactionSpec is a list of interaction properties
managedConnectionFactory defines the connection factory properties
connectionSpec is the connection class used
resourceAdapter is the Resource Adapter used by either specifying the project name or a list of properties

Additional Tasks

These are utility tasks, useful, but not required for artifact generation.

The createProject task can be used to create a workspace project.

<adapter:createProject 
		projectName="taderc99Project" 
		projectType="Web" 
		runtimeName="J2EE Runtime Library"
		addToEAR="yes"
		EARProjectName="TestEAR"/>

Where:

projectName is the name of the project
projectType is the type can be Java, Web and EJB, case insensitive
runtimeName (optional) is the runtime name as defined in Window->Preferences->Server->Installed Runtimes
addToEAR (optional) valid values are
- yes
- no
- true
- false
EARProjectName (optional) is the EAR project name

The importResourceAdapter task can be used to create a connector project.

<j2c:importResourceAdapter 
		connectorModule="cicseci602"
		connectorFile="D:\IBM\SDP70\ResourceAdapters\cics15\cicseci602.rar" 
		targetRuntime="J2EE Runtime Library"
		addToEAR="yes"
		EARProjectName="TestEAR"/>

Where:

connectorModule is the connector project name
connectorFile is the relative or full file system path to the connector file
targetRuntime is the runtime name as defined in Window > Preferences > Server > Installed Runtimes
addToEAR (optional) is
- yes
- no
- true
- false
EARProjectName (optional) is the EAR project name

Defining Properties

Discovery agents and workspace writer are referred by their name (QName), which is uniquely identified. To find all registered discovery agents, workspace resource Writers, and Import configurations, use the displayAll.xml script found in the sample directory.

As observed in the example scripts, the values passed to the discovery agents or resource writers are defined by propertyGroup and propertyElement tags. A property group defines a logical grouping of properties through a nested structure. The structure layout and the contained group and property names, should be described in the discovery agent or resource writer documentation.

Properties are defined by a pair of name, value attributes. The name is actually a property defined internally by the discovery agent or resource writer and it is used to pass the value along. It is important to get the name right. If the name is not recognized by the component the value will not be set.