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.

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.

  1. 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)
  2. 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
  3. 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>
  4. 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
  5. 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="type="com/ibm/adapter/cobol/writer:JAVA_WRITER">
            <propertyElement name="Java Type Name/Overwrite existing class" value="true"/>
            <propertyElement name="Java Type Name/Project Name" value="Test"/>
            <propertyElement name="Java Type Name/Package Name" value="com.ibm.test"/>
					 <propertyElement name="Java Type Name/Class Name" 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 is case sensitive and can be either a full file system path or a workspace relative one.

Before running the above mentioned script the following fix is required:
  1. Close any workspace that is open.
  2. Browse to the RAD_INSTALL_DIR/rad/eclipse/plugins/com.ibm.adapter.command.6.0.0plugin directory.
  3. Open the plugin.xml file and remove the following lines:
    <library name="runtime/command-ant.jar">
    		<export name="*"/>
    />library>
  4. Save the file.
  5. Open a command prompt and invoke RAD with the clean parameter: RAD_INSTALL_DIR/rationalsdp.exe -clean. You need to make this correction only once.
Steps to run the above script:
  1. Create a Java project that the script will point to.
  2. In the newly created Java project create an XML file dataType.xml and copy the above script into.
  3. Change the properties within the script file accordingly.
  4. Run the Ant script. Make sure it runs in the same JRE as the workspace.
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.