Monday, June 16, 2008

Deploying ESB projects (SOA Suite 10g) via ANT

These instructions describe how to use ANT to deploy an ESB 10g project.

Prerequisites

1. Unzip JAXB 2.1.7 (jaxb-2_1_7.zip) (8,898,843 bytes) under /u01/esbdeploy.

2. Unzip Jakarta Commons HttpClient 3.1 (commons-httpclient-3.1.zip) (2,898,781 bytes) under /u01/esbdeploy.

3. Install Oracle SOA Suite 10g (10.1.3) under /u01/app/oracle/product/10.1.3/soa_1.

4. These instructions assume the following directory format: 
/u01/esbdeploy 
/u01/esbdeploy/commons-httpclient-3.1 
/u01/esbdeploy/jaxb-ri 
/u01/esbdeploy/ESBProject1 
/u01/app/oracle/product/10.1.3/soa_1  

Details
1. Create a build.xml in the ESB project directory (e.g., /u01/esbdeploy/ESBProject1/build.xml):
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<project name="ESBDeploymentProject" default="usage">

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - PROPERTIES
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <property environment="env"/>
    <property name="esbProjectToDeploy" value="${basedir}"/>
    <property name="deploymentPlanFilename" value="${esbProjectToDeploy}/DeploymentPlan.xml"/>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - Import, to enable the custom ESB Metadata Deployment ant tasks ...
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <import file="${basedir}/../ESBMetadataMigrationTaskdefs.xml"/>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - TEST Deployment Automation
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <target name="DeployESBProjects">
        <deployESBProjects esbMetadataServerHostname="${hostname}"
                           esbMetadataServerPort="${http.port}"
                           userName="${admin.user}"
                           password="${admin.password}">
            <esbProject directory="${esbProjectToDeploy}"/>
        </deployESBProjects>
    </target>

    <target name="ExtractESBDeploymentPlan">
        <delete file="${deploymentPlanFilename}" verbose="true"/>
        <extractESBDeploymentPlan
           sourceDir="${basedir}"
           deploymentPlanFile="${deploymentPlanFilename}"/>
    </target>

    <target name="UndeployESBEntities">
        <undeployESBEntities esbMetadataServerHostname="${hostname}"
                             esbMetadataServerPort="${http.port}"
                             userName="${admin.user}"
                             password="${admin.password}">
            <import file="${esbProjectToDeploy}/esb_guids.properties"/>
        </undeployESBEntities>
    </target>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - USAGE
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <target name="usage">
      <echo>
========   Environment   =====================================================
  ORACLE_HOME                           = ${env.ORACLE_HOME}
  ANT_HOME                              = ${env.ANT_HOME}
  JAVA_HOME                             = ${env.JAVA_HOME}
========   Properties    =====================================================
  basedir                               = ${basedir}
  hostname                              = ${hostname}
  http.port                             = ${http.port}
  admin.user                            = ${admin.user}
  sourceDirectory                       = ${esbProjectToDeploy}
  jaxb.v2.0.2.home                      = ${jaxb.v2.0.2.home}
  soa.suite.home                        = ${soa.suite.home}
  imported.basedir                      = ${imported.basedir}
  deploymentPlanFilename                = ${deploymentPlanFilename}
  commons.httpclient.home               = ${commons.httpclient.home}
  ant.file.ESBMetadataMigrationTaskdefs = ${ant.file.ESBMetadataMigrationTaskdefs}
==============================================================================
      </echo>
        <exec executable="ant" dir="${esbProjectToDeploy}" vmlauncher="false">
            <arg value="-projecthelp"/>
        </exec>
    </target>

</project>
2. Create the file ant-oraesb.properties in the top-level deployment directory
(e.g., /u01/esbdeploy/ant-oraesb.properties), and update the values highlighted in red:
oc4jinstancename = oc4j_soa
admin.user       = oc4jadmin
admin.password   = welcome1
hostname         = oradev.oracle.com
http.port        = 7777
3. Extract ESBMetadataMigration.jar from $ORACLE_HOME/integration/esb/deployment/documentation.zip
and place it in the top-level deployment directory (e.g., /u01/esbdeploy/ESBMetadataMigration.jar).

cd /u01/esbdeploy
export $ORACLE_HOME=/u01/app/oracle/10.1.3/soa_1
unzip -j $ORACLE_HOME/integration/esb/deployment/documentation.zip "Enterprise Service Bus (ESB) 10.1.3.1 Deployment Automation_attachments/ESBMetadataMigration.jar"
4. Create the file ESBMetadataMigrationTaskdefs.xml in the top-level deployment directory
(e.g., /u01/esbdeploy/ESBMetadataMigrationTaskdefs.xml), and update the values highlighted in red if you decide to use a different directory structure:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - The import of this ant build file, by another ant build file, enables the
   - use of the custom ant tasks present in ESBMetadataMigration.jar
   - Doug Gschwind
   - 12 Dec 2006
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<project name="ESBMetadataMigrationTaskdefs">

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - PROPERTIES, Subject to the installation environment
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <property name="commons.httpclient.home" value="/u01/esbdeploy/commons-httpclient-3.1"/>
    <property name="jaxb.v2.0.2.home" value="/u01/esbdeploy/jaxb-ri"/>
    <property name="soa.suite.home" value="/u01/app/oracle/product/10.1.3/soa_1"/>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   - Custom ant task definitions, to enable import.
   - This section should be treated as immutable upon installation.
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

    <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.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>
5. Create a deploy script /u01/esbdeploy/esb_deploy.sh (this step will change once the ANT script is improved upon):
#
# Set the environment
#
export ORACLE_HOME=/u01/app/oracle/product/10.1.3/soa_1
export JAVA_HOME=$ORACLE_HOME/jdk
export PATH=$ORACLE_HOME/ant/bin:$PATH
export ESBDEPLOYBASE=/u01/esbdeploy
export ANT_HOME=$ORACLE_HOME/ant
export CLASSPATH=$ORACLE_HOME/integration/esb/lib/xmlparserv2.jar:$ESBDEPLOYBASE/jaxb-ri/lib/jaxb-impl.jar:$ESBDEPLOYBASE/jaxb-ri/lib/activation.jar:$ESBDEPLOYBASE/jaxb-ri/lib/jaxb1-impl.jar:$ESBDEPLOYBASE/jaxb-ri/lib/jaxb-api.jar:$ESBDEPLOYBASE/jaxb-ri/lib/jaxb-impl.jar:$ESBDEPLOYBASE/jaxb-ri/lib/jsr173_1.0_api.jar

#
# Set the project directory to deploy
#
export PROJECTBASE=$ESBDEPLOYBASE/ESBProject1

#
# Dynamically create the 'esb_guids.properties' file
#
export ESBGUIDFILE=esb_guids.properties
cat /dev/null > $PROJECTBASE/$ESBGUIDFILE
for i in `ls $PROJECT_DIR/*.esbsys`
do
echo "<system guid=`cat $i | grep guid | grep 'system name' | awk '{print $3}' | cut -c 6-39`/>" >> $PROJECTBASE/$ESBGUIDFILE
done
for i in `ls $PROJECT_DIR/*.esbsvc`
do
echo "<service guid=`cat $i | grep guid | grep 'service name' | awk '{print $3}' | cut -c 6-39`/>" >> $PROJECTBASE/$ESBGUIDFILE
done

#
# Build and deploy the project
#
cd $PROJECTBASE
$ORACLE_HOME/ant/bin/ant -lib $ORACLE_HOME/jdk/lib -propertyfile $ESBDEPLOYBASE/ant-oraesb.propertes

The following valid targets are also available:
    ExtractESBDeploymentPlan
    DeployESBProjects
    UndeployESBEntities
    usage

Applicable Versions
  • Oracle SOA Suite 10g (10.1.3.3)
  • JAXB 2.1.7
  • Jakarta Commons HttpClient 3.1

References
  • http://www.oracle.com/technology/tech/soa/soa-suite-best-practices/auto-deploy.html
  • http://technology.amis.nl/blog/?p=2371
  • http://www.it-eye.nl/weblog/2007/11/28/deploying-esb-projects-using-ant/
  • http://technology.amis.nl/blog/?p=1655

Ahmed Aboulnaga

1 comment:

Anonymous said...

When I try to use import file like your example within undeployESBEntities. ANT fails with a RuntimeException: Unsupport Task : import.

Is there another way to include the values from my ESBGUIDFILE?