13 Enterprise Service Bus Ant Deployment Feature

This chapter describes support for the ESB Ant deployment feature in the Oracle Application Server release 10.1.3.4.

This chapter contains the following topics:

Overview of Ant Deployment Feature
Ant Installation
Deployment of Ant Tasks
ESB Ant Deployment Custom Tasks

Overview of Ant Deployment Feature

The Ant deployment feature includes a set of custom Ant tasks that are used for ESB service deployment automation. ESB Ant deployment feature supports working with ESB metadata and enables you to deploy or undeploy the metadata to an ESB metadata (design time) server using custom Ant tasks, with or without property substitution taking place.

Ant Installation

You need to download and install Ant from this location

http://ant.apache.org/bindownload.cgi

Perform the following steps:

Install Ant and the dependent JAR files.
Edit the ESBMetadataMigrationTaskdefs.xml file to point to your JAR files.
In JDeveloper, create a simple ESB project called AntTest with a routing service and a fileout adapter.

Create an AntTestBuild.xml file, as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<project name="AntTest" default="usage">
    <property name="esbProjectLocation" value="C:\mywork\ESBTests\AntTest"/>
    <property name="deploymentPlanFile" value=".\AntTestDeploymentPlan.xml"/>
  <import file="${basedir}/ESBMetadataMigrationTaskdefs.xml"/>
  <target name="AntTest">
    <delete file="${deploymentPlanFile}"/>
    <extractESBDeploymentPlan
        sourceDir= "${esbProjectLocation}" 
        deploymentPlanFile="${deploymentPlanFile}"/>
  </target>
    <target name="AntTestDeploy">
<deployESBProjects esbMetadataServerHostname="localhost"
          esbMetadataServerPort="8888"
                           userName="oc4jadmin"
                           password="welcome1">
   <esbProject directory="${esbProjectLocation}"/>
</deployESBProjects>
    </target>
<target name="AntTestDeployPlan">
    <deployESBSuitcase sourceDirectory="${esbProjectLocation}"
           deploymentPlanFilename="${deploymentPlanFile}"
                       esbMetadataServerHostname="localhost"
                       esbMetadataServerPort="8888"
                       forcedDeployment="true"/>
</target>
   <target name="usage">
<exec executable="ant" dir="${basedir}" vmlauncher="false">
    <arg value="-projecthelp"/>
</exec>
    </target>
</project>

Set the path to access JRE and Ant binaries.
Deploy the project using JDeveloper. This has to be done only once in the JDeveloper environment.
Run the extracted Ant task using the following command: "ant -f AntTestBuild.xml AntTest."
Optionally, edit the newly created AntTestDeploymentPlan.xml file.
Delete the project from the ESB console.
Deploy the project with the plan "ant -f AntTestBuild.xml AntTestDeployPlan." To deploy directly without a plan, you can run the deploy project Ant task "ant -f AntTestBuild.xml AntTestDeploy."
Test using the embedded EM test page.

Deployment of Ant Tasks

You can use the Ant scripts to register an ESB project from the command line. To do this, you need to download the ESB deployment package from the following location:

OracleAS_HOME\integration\esb\deployment\documentation.zip

which contains the following custom tasks:

The deployESBProjects task enables one to many ESB projects in JDeveloper to be deployed to a given ESB metadata server. The ESB project artifacts found in the identified projects will be deployed as is, that is, without any property substitution taking place during the deployment process. This task is the automated equivalent of manually visiting each ESB project within JDeveloper, to exercise the Register with ESB function in that context.
The undeployESBEntities task enables one to many ESB systems, service groups, or services to be deleted (or undeployed) from the identified ESB metadata server, where each entity to be undeployed is uniquely identified by its guid. This task is the automated equivalent of manually locating each ESB system, service group, or service within the ESB console and, then clicking Delete.
The extractESBDeploymentPlan task supports the extraction of all properties that are allowed to vary for all of the ESB systems, service groups, and services found within a single ESB project that is owned and maintained by JDeveloper. The extracted collection of properties is known as a deployment plan and is placed into an XML document on disk.
The deployESBSuitcase task supports deploying the ESB project artifacts found in the identified JDeveloper ESB project directory (and subdirectories) to the identified ESB metadata server, while applying the properties found in the specified deployment plan to those artifacts. Both the ESB project artifacts and the deployment plan are read-only.

Deployment Ant Tasks Sample File

Example 13-1 describes the ESBMetadataMigrationTaskdefs.xml sample file.

Example 13-1 The ESBMetadataMigrationTaskdefs.xml Sample File

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<project name="ESBMetadataMigrationTaskdefs">
<!-- PROPERTIES, unique  to the installation environment -->
 <property name="commons.httpclient.home" value="C:/src/esbDeploymentAutomation"/>
 <property name="jaxb.v2.0.2.home"  value="C:/src/esbDeploymentAutomation/jaxb-ri-20070122"/>
 <property name="soa.suite.home" value="C:/product/10.1.3.1/OraESB_1"/>
<!--- Custom ant task definitions, do not change below this line -->
    <dirname property="imported.basedir"
 file="${ant.file.ESBMetadataMigrationTaskdefs}"/>
    <taskdef resource="oracle/tip/esb/client/anttasks/antlib.xml">
        <classpath>
            <pathelement location="${imported.basedir}/ESBMetadataMigration.jar"/>
            <pathelement
 location="${commons.httpclient.home}/commons-httpclient-3.0.1.jar"/>
            <pathelement location="${soa.suite.home}/lib/xmlparserv2.jar"/>
            <pathelement
 location="${soa.suite.home}/integration/esb/lib/commons-logging.jar"/>
            <pathelement
 location="${soa.suite.home}/integration/esb/lib/commons-codec-1.3.jar"/>
            <pathelement
 location="${soa.suite.home}/integration/esb/lib/oraesb.jar"/>
            <pathelement location="${jaxb.v2.0.2.home}/lib/activation.jar"/>
            <pathelement location="${jaxb.v2.0.2.home}/lib/jaxb-api.jar"/>
            <pathelement location="${jaxb.v2.0.2.home}/lib/jsr173_1.0_api.jar"/>
            <pathelement location="${jaxb.v2.0.2.home}/lib/jaxb-impl.jar"/>
        </classpath>
    </taskdef>
</project>

Example 13-2 describes the AntTestBuild.xml sample file.

Example 13-2 The AntTestBuild.xml Sample File

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<project name="AntTest" default="usage">
    <property name="esbProjectLocation" value="C:\mywork\ESBTests\AntTest"/>
    <property name="deploymentPlanFile" value=".\AntTestDeploymentPlan.xml"/>
  <import file="${basedir}/ESBMetadataMigrationTaskdefs.xml"/>
  <target name="AntTest">
    <delete file="${deploymentPlanFile}"/>
    <extractESBDeploymentPlan
        sourceDir= "${esbProjectLocation}" 
        deploymentPlanFile="${deploymentPlanFile}"/>
  </target>
    <target name="AntTestDeploy">
<deployESBProjects esbMetadataServerHostname="localhostÒ
 esbMetadataServerPort="8888"
userName="oc4jadminÒ password="welcome1">
      <esbProject directory="${esbProjectLocation}"/>
</deployESBProjects>
    </target>
<target name="AntTestDeployPlan">
    <deployESBSuitcase sourceDirectory="${esbProjectLocation}Ò                      
deploymentPlanFilename="${deploymentPlanFile}"
esbMetadataServerHostname="localhostÒ esbMetadataServerPort="8888"
forcedDeployment="true"/>
</target>
   <target name="usage">
<exec executable="ant" dir="${basedir}" vmlauncher="false">
    <arg value="-projecthelp"/>
</exec>
    </target>
</project>

ESB Ant Deployment Custom Tasks

This section describes the following ESB Ant deployment custom tasks:

deployESBProjects
undeployESBEntities
extractESBDeploymentPlan
deployESBSuitcase

deployESBProjects

deployESBProjects is a custom Ant task that can be used to deploy one to many ESB projects, which are created and maintained by JDeveloper, to a given ESB metadata server. This task provides identical behavior to that of JDeveloper's Register with ESB function, with the additional functionality of Automatic refresh or resynchronization of the JDeveloper-owned and maintained ESB project artifacts. If JDeveloper is used to manually deploy one or more of those given ESB projects using the Register with ESB function, then the ESB project metadata first needs to be refreshed from the ESB metadata server.

Parameters

The attribute and description of the parameters are described in the following table:

Attribute	Description	Required
esbMetadataServerHostname	The host name of the computer that is supporting the ESB Metadata Server of interest.	Yes
esbMetadataServerPort	The port number of the ESB Metadata Server.	Yes
userName	The login name that has permission to deploy or undeploy ESB systems, service groups, and services using the ESB console, typically, `oc4jadmin`.	Yes
password	The password for the `userName` account.	Yes

Note:

The esbMetadataServerPort for a given ESB metadata server instance can be identified by the port number used to interact with the ESB control/console for the given machine. The URL used to interact with the ESB control/console for the desired ESB instance will use that same port number.

Parameter Specified as Nested Elements

The deployESBProjects custom task supports one to many nested esbProject tasks. An esbProject task cannot be nested within another esbProject task. The parameters for an esbProject task are documented in the following table:

Attribute	Description	Required
directory	The top-level directory of an ESB project created/maintained by JDeveloper.	Yes

System Response

The custom Ant task will intimate you with the semantic validation errors in the case where the task has not been defined properly, as well as the output, informing you of its progress. On completion of the task, open the ESB console to ensure that your ESB systems, service groups, and services have been deployed to the ESB metadata server of interest.

Examples

Example 13-3 requests that the five ESB projects be deployed to the ESB metadata server that is running on the local host and is to be contacted on the local host at port 8889. The ESB projects will be deployed in the following order: CustomerData, CustomerData5, CustomerData8, CustomerData9, and CustomerData10. It is important to note that the directories specified are the top-level directory for each of those five projects. Within each directory (or one of its subdirectories), ESB project artifacts (files with the following file name extensions: .esb, .esbgrp, .esbsvc, .esbsys, .xml, .xsd, .xsl, .xslt, and .wsdl) can be found.

Example 13-3 Example for deployESBProjects

<target name="test.DeployESBProjects">
    <deployESBProjects esbMetadataServerHostname="localhost"
     esbMetadataServerPort="8889"
                       userName="oc4jadmin"
                       password="oc4jadmin">
                       protocol="https">
                      <truststore="C:\JDev_10134\jdk\jre\lib\security\cacerts">
        <esbProject
directory="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData"/>
        <esbProject directory="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData5"/>
        <esbProject directory="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData8"/>
        <esbProject directory="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData9"/>
        <esbProject directory="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData10"/>
    </deployESBProjects>
</target>

undeployESBEntities

undeployESBEntities is a custom Ant task that can be used to undeploy one to many ESB entities (systems, service groups, and services) that have been previously deployed to the identified ESB metadata server. For simplified dependency management and error handling, all identified services are undeployed first, followed by all identified service groups, followed by all identified Systems. The task does require that at least one system, service group, or service be specified to be undeployed. ESB systems, service groups, and services identified for undeployment can be specified in any order.

Parameters

The attribute and description of the parameters are described in the following table:

Attribute	Description	Required
esbMetadataServerHostname	The host name of the computer that is supporting the ESB Metadata Server of interest.	Yes
esbMetadataServerPort	The port number of the ESB Metadata Server.	Yes
userName	The login name that has permission to delete ESB Systems, Service Groups, and Services using the ESB console, typically, `oc4jadmin`.	Yes
password	The password for the `userName` account.	Yes

Note:

Parameter Specified as Nested Elements

The undeployESBEntities custom task supports one to many nested system, service group, and service tasks. These nested tasks cannot be nested within each other, as each task must be a peer of the others. The parameters for the system, service group, and service task are identical and are documented in the following table:

Attribute	Description	Required
guid	This value uniquely identifies the ESB entity that is to be undeployed. The guid of any ESB entity can be found in the guid attribute of the System, Service Group, or Service element of the corresponding .esbsys, .esbgrp, or .esbsvc file, respectively, that JDeveloper maintains. The guid for each entity can also be found in the guid attribute of the elements in the metadata.xml file that is produced using ESB's export command-line utility. Note: The `metadata.xml` file is housed in the ZIP file that the export command-line utility produces.	Yes

System Response

The custom Ant task will intimate you with the semantic validation errors in the case where the task has not been defined properly, as well as the output, informing you of its progress. On completion of the task, open the ESB console to see that your ESB systems, service groups, and services have been undeployed from the ESB metadata server of interest.

Examples

Example 13-4 requests that the five ESB systems, two service groups, and two services identified be undeployed from the ESB metadata (design time) server that is running on the local host, and is to be contacted on the local host at port 8889. Again, for simplified dependency management and error handling, the two identified Services are undeployed first, followed by the two identified service groups, followed by the five identified systems.

Example 13-4 Example for undeployESBEntities

<target name="test.UndeployESBEntities">
    <undeployESBEntities esbMetadataServerHostname="localhost"
                         esbMetadataServerPort="8889"
                         userName="oc4jadmin"
                         password="oc4jadmin">
                         protocol="https">
        <system guid="8D61C3F0871111DB8F2675C60E6C31C6"/>
        <serviceGroup guid="0EB5F380896111DBBFBC9530C01627AC"/>
        <service guid="0547F370841611DBBFCF2D9BF80323FA"/>
        <service guid="05458270841611DBBFCF2D9BF80323FA"/>
        <system guid="86443990871611DB8F2675C60E6C31C6"/>
        <serviceGroup guid="B90E6B70895F11DBAF1483EEF470B835"/>
        <system guid="A62C91C1841511DBBFCF2D9BF80323FA"/>
        <system guid="D9F290E1896011DBBFBC9530C01627AC"/>
        <system guid="A9B213C1895F11DBAF1483EEF470B835"/>
    </undeployESBEntities>
</target>

extractESBDeploymentPlan

extractESBDeploymentPlan is a custom Ant task that supports extracting the deployment plan from a JDeveloper ESB project source directory into the identified deploymentPlanFile.

Preconditions

The identified ESB project must have been deployed at least once using JDeveloper's Register with ESB function. This is due to the fact that the underlying ESB artifacts will be modified as a result of the Register with ESB function, and this task expects the artifacts to be in that fully specified state.

Additionally, the deployment plan file to be created is protected from being inadvertently overwritten by the execution of this task. If the deployment plan file to be created already exists when this task is executed, then the task will be terminated and inform you of this condition.

Parameters

The attribute and description of the parameters are described in the following table:

Attribute	Description	Required
sourceDir	The absolute or relative top level directory used by JDeveloper to house the ESB project, must point to a directory that both exists and can be read, and must contain at least one ESB artifact.	Yes
deploymentPlanFile	The absolute or relative file name of the file that is to be created as a result of this task and must point to a file that can be written.	Yes

Parameter Specified as Nested Elements

The extractESBDeploymentPlan custom task supports no nested elements.

System Response

The custom Ant task will intimate you with the semantic validation errors in the case where the task has not been defined properly, as well as the status of its ability to create the deployment plan. On success, you will be informed of the full path of the created deployment plan file.

Examples

Example 13-5 describes the task to extract the deployment plan information that is currently held in the ESB project artifacts found in the C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData8 directory, into the file identified as ../CustomerData8DeploymentPlan.xml.

Example 13-5 Example for extractESBDeploymentPlan

<target name="test.ExtractESBDeploymentPlan">
    <extractESBDeploymentPlan
sourceDir="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData8"
        deploymentPlanFile="../CustomerData8DeploymentPlan.xml"/>
</target>

Example 13-6 is identical to the previous with the exception that the deployment plan will be deleted off the disk before the task is executed.

Example 13-6 Example for extractESBDeploymentPlan

<target name="test.ExtractESBDeploymentPlan">
    <property name="deploymentPlan" value="../CustomerData8DeploymentPlan.xml"/>
    <delete file="${deploymentPlan}"/>
    <extractESBDeploymentPlansourceDir="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/
CustomerData8" deploymentPlanFile="${deploymentPlan}"/>
</target>

deployESBSuitcase

deployESBSuitcase is a custom Ant task that can be used to deploy one ESB project that has been created and is otherwise maintained by JDeveloper, after the contents of the designated deployment plan have been applied. The task provides identical behavior to that of JDeveloper's Register with ESB function, with the following differences:

Application of the deployment plan to the found ESB artifacts is not done in JDeveloper's Register with ESB function, but is done with this task.
Automatic refresh/resync of the JDeveloper artifacts is done in JDeveloper's Register with ESB function, but is not done with this task.

If this task is used to deploy one to many ESB projects and if JDeveloper is later desired to be used to manually deploy one or more of those given ESB projects using the Register with ESB function, then the ESB project metadata will first need to be refreshed from the ESB metadata server.

Parameters

The attribute and description of the parameters are described in the following table:

Attribute	Description	Required
sourceDir	This is the top level directory that houses all of the ESB project-related artifacts maintained by JDeveloper, that is to say, all .esb, .esbgrp, .esbsvc, .esbsys, .xml, .xsd, .xsl, .xslt, and .wsdl files maintained as part of the project	Yes
deploymentPlanFile	This indicates a file that houses the deployment plan that exists and can be read.	Yes
esbMetadataServerHostname	The host name of the computer that is supporting the ESB Metadata Server of interest.	Yes
esbMetadataServerPort	The port number of the ESB Metadata Server.	Yes
forcedDeployment	Whether or not to force the deployment and ignore conflicts or version and/or time stamp mismatches. This attribute has a default value of true. False is also accepted.	No

Note:

Parameter Specified as Nested Elements

The deployESBSuitcase custom task supports no nested elements.

System Response

The custom Ant task will intimate you with the semantic validation errors in the case where the task has not been defined properly, as well as output informing you of its progress. On completion of the task, open the ESB console of the appropriate ESB metadata server to verify that the ESB systems, service groups, and services have been appropriately deployed. Additionally, you can inspect the aspects of each deployed entity to verify that the properties held in the specified deployment plan were those that were used at deployment time and are what the metadata server is in fact using.

In case the conflicts do exist between the artifacts held by the ESB metadata server and those hold in the JDeveloper-owned and managed project directory, you will see output from the Ant target that leverages this task that is similar to the following:

[deployESBSuitcase] Deployment Attempt Response :
[deployESBSuitcase] <deploymentSummary>
[deployESBSuitcase]    <message>Entity Deployment Failed</message>
[deployESBSuitcase]    <conflicts>
[deployESBSuitcase]       <conflict qname="AdapterServices"
 guid="A3CC9DE1AEF811DBBFF7559FF9492F22">
[deployESBSuitcase]          <lastModifiedTime>Tue Feb 27 15:59:03 MST
 2007</lastModifiedTime>
[deployESBSuitcase]          <lastModifiedUser>JDev_temp_ESBSamples
_AdapterServices_localhost</lastModifiedUser>
[deployESBSuitcase]       </conflict>
[deployESBSuitcase]       <conflict qname="AdapterServices.databaseAdapter"
 guid="CC826930AEF911DBBFF7559FF9492F22">
[deployESBSuitcase]          <lastModifiedTime>Tue Feb 27 15:59:03 MST
 2007</lastModifiedTime>
[deployESBSuitcase]          <lastModifiedUser>JDev_temp_ESBSamples
_AdapterServices_localhost</lastModifiedUser>
[deployESBSuitcase]       </conflict>
[deployESBSuitcase]    </conflicts>
[deployESBSuitcase] </deploymentSummary>

In this case, you can opt to use forced deployment, by specifying the forcedDeployment attribute to have a value of true, in which case this task should then succeed on the subsequent attempt.

Examples

Example 13-7 describes the custom Ant task to read the ESB project and all of its artifacts from the C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData8 directory and all of its subdirectories, apply the deployment plan found in ../CustomerData8DeploymentPlan.xml to those artifacts (without changing the artifacts), and deploying the resulting artifacts to the ESB Metadata Server that is running on the localhost machine that is listening on port 8889. The resulting deployed artifacts are not retained as they will be regenerated each time the task is executed. Because the forcedDeployment attribute is given a value of false, if any conflicts are detected at deployment time, then the deployment attempt will be aborted.

Example 13-7 Example for deployESBSuitcase

<target name="test.DeployESBSuitcase">
    <deployESBSuitcase
sourceDir="C:/Oracle/product/JDeveloper/v10.1.3.1/jdev/mywork/ESBSamples/CustomerData8"
                       deploymentPlanFile="../CustomerData8DeploymentPlan.xml"
                       esbMetadataServerHostname="localhost"
                       esbMetadataServerPort="8889"
                       forcedDeployment="false"/>
</target>