You can use Ant scripts to invoke J2C components, and these Ant
scripts can be called from the workbench or from the command line.
When performing application development, it is very common that the
source of application artifacts come from a metadata repository. These repositories
are typically browsed for artifacts, and subsets of the artifacts are selected,
from which application components are then generated. This process is usually
done through the workbench which invokes the underlying API to do the actual
import. The same import can also be done using an Ant definition file which
mimics the interaction between the workbench and the underlying API.
Apache Ant is a Java-based build tool. Ant configuration files
have the advantage that they can be invoked either from command line or within
the workbench. Since an Ant configuration file is in essence an XML file,
it can be modified or built entirely by hand and re-run without having to
load the workbench.
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 Import cycle
In
general, there are two steps involved during an import cycle, each of which
is done by a distinct component:
- Discovery agents perform the actual import of data and produce proprietary
metadata which are called import result.
- Resource writers consume the import result and 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
Ant definition file has two distinct sections that store such information,
one for the Discovery Agent component and one for the Resource Writer component.
- 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
- importProperties 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:
<workspaceResourceWriter type="ResourceWriterName">
<propertyElement name="PropertyName" value="PropertyValue"/>
</workspaceResourceWriter>
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 and C) 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.
The Command section of the Ant script looks like this:
<command commandID="CommandID">
<fileset dir="." includes="AntFile"/>
</command>
Where:
- command is the command to drive the execution
- fileset is a mandatory parameter used as an action trigger
and it always points to the Ant file itself
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"?>
<project name="com.ibm.adapter.command" default="DataType">
<target name="DataType">
!-- perform import -->
<discoveryAgent type="com/ibm/adapter:CobolDiscoveryAgent">
<importResource name="CobolFile" value="\Test\taderc99.ccp"/>
<importProperties>
<propertyElement name="Platform name" value="Win32"/>
</importProperties>
<searchParameters>
<propertyElement name="DFHCOMMAREA"/>
</searchParameters>
!-- execute import command -->
<command commandID="com.ibm.adapter.command.PerformImportCommand">
<fileset dir="." includes="**/dataType.xml"/>
/command>
!-- write to workspace -->
<workspaceResourceWriter type="com/ibm/adapter/cobol/writer:JAVA_WRITER">
<propertyElement name="JavaTypeName/JavaProjectName" value="Test"/>
<propertyElement name="JavaTypeName/JavaPackageName" value="com.ibm.test"/>
<propertyElement name="JavaTypeName/JavaClassName" value="Taderc99"/>
</workspaceResourceWriter>
!-- execute write command -->
<command commandID="com.ibm.adapter.command.WriteToWorkspaceCommand">
<fileset dir="." includes="**/dataType.xml"/>
</command>
</target>
</project>
The value for the CobolFile property
can be a full file system path or a workspace relative one.
Steps to
run the above script:
- Create a Java project that the script will point to.
- In the newly created Java project create an XML file dataType.xml
and copy the above script into.
- Change the properties within the script file accordingly.
- Run the Ant script. Make sure it runs in the same JRE as the workspace.