ANT SCRIPT FOR SOA

Setting up ant for automated composite management All component management tasks that can be performed manually through the web-based Oracle Enterprise Manager Fusion Middleware Control console can also be executed with a script through the command-line utility ant. In this section, we describe how to use ant to start up, shut down, activate, and retire composites, as well as package and deploy them. Oracle SOA Suite 11g ships all necessary ant scripts to perform these tasks, and they are quite easy to use. Setting the environment Here, we will describe how to set both Linux and Microsoft Windows based environments to allow you to run your ant commands through the command line. Your ant scripts do not have to be installed on the same machine running Oracle SOA Suite 11g. In fact, it is not unusual to dedicate a single machine or server, which would host your ant scripts, allowing you to centralize the startup, shutdown, and deployment of your SOA composites to multiple target environments. You will also see how ant enables automated build management for your environment in later sections of this chapter. Setting the environment path for ant In your environment, we assume that Oracle SOA Suite 11g is installed, which is recommended, as it will include all the required binaries to run ant. The Middleware Home, the Oracle SOA Suite 11g Home, the Java Home, WebLogic Server username and password, and SOA server host and port will need to be updated appropriately to reflect your environment. Directory locations and JDK versions may differ depending on the patchset of Oracle SOA Suite 11g installed. These commands must be executed to set your environment paths before running any ant command. On Linux/Unix In this chapter, we will assume that your code will reside under $CODE under the same Unix account where the Middleware Home and other binaries are installed. This is because the ant scripts require access to specific product libraries. The scripts assume a bash-based shell, so some changes may be required if other shells are used. To set your environment, we recommend first creating a shell script setAntEnv.sh with the following content while keeping in mind to replace the highlighted values to suit your environment and installation: export USERNAME=weblogic export PASSWORD=welcome1 export SOAHOST=soahost1 export SOAPORT=8001 export SOAURL=http://${SOAHOST}:${SOAPORT}export CODE=/u01/svn/SOA11g export MW_HOME=/u01/app/oracle/Middleware export ORACLE_HOME=$MW_HOME/Oracle_SOA1 export JAVA_HOME=$MW_HOME/jdk160_24 export ANT_HOME=$MW_HOME/modules/org.apache.ant_1.7.1 export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$ANT_HOME/lib:$PATH:. Don't forget to change the permissions of the script to executable: chmod 750 setAntEnv.sh Prior to running any ant command in the remainder of the chapter, simply source this shell script once to set your environment for your session as follows: source setAntEnv.sh Finally, make sure to change to the $ORACLE_HOME/bin directory before running any of the ant commands: cd $ORACLE_HOME/bin On Windows We will assume that your code will reside under %CODE%. To set your environment, we recommend first creating a shell script setAntEnv.bat with the following content: set USERNAME=weblogic set PASSWORD=welcome1 set SOAHOST=soahost1 set SOAPORT=8001 set SOAURL=http://soaHost:soaPort set CODE=c:\svn\SOA11g set MW_HOME=C:\Oracle\Middleware set ORACLE_HOME=%MW_HOME%\Oracle_SOA1 set JAVA_HOME=%ORACLE_HOME%\jdk160_24 set ANT_HOME=%ORACLE_HOME%\modules\org.apache.ant_1.7.1 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%ANT_HOME%\lib;%PATH% Make sure to update the highlighted text in the preceding script, to reflect your actual environment and installation. In your Windows environment, if you do not have Oracle SOA Suite 11g and instead only have Oracle JDeveloper 11g installed, only a few modifications are required, and you should use the following commands instead: set USERNAME=weblogic set PASSWORD=welcome1 set SOAHOST=soahost1 set SOAPORT=8001 set SOAURL=http://%SOAHOST%:%SOAPORT% set CODE=c:\svn\SOA11g set ORACLE_HOME=C:\Oracle\jdev\jdeveloper set JAVA_HOME=%ORACLE_HOME%\..\jdk160_24 set ANT_HOME=%ORACLE_HOME%\..\modules\org.apache.ant_1.7.1 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%ANT_HOME%\lib;%PATH% But only for installations of Oracle JDeveloper 11g, you must also perform a one-time copy of ant-contrib-1.0b3.jar. The file can be downloaded from http://sourceforge.net/projects/ant-contrib/files/ant-contrib/. Simply copy the file to %ANT_HOME%\lib as follows: copy c:\temp\ant-contrib-1.0b3.jar %ANT_HOME%\lib Now that your batch script is created, simply run it once in the command prompt to set your environment for your session: setAntEnv.bat Finally, make sure to change to the %ORACLE_HOME%\bin directory before running any of the ant commands: cd %ORACLE_HOME%\bin All ant commands in the remainder of this chapter will be Linux based. For Windows, simply replace the Linux specific environment variables such as $USERNAME and $SOAHOST with their Windows equivalent of %USERNAME% and %SOAHOST%. Also ensure that the slashes are reversed in the code paths. For example, $CODE/HelloWorld/deploy/sca_HelloWorld_rev1.0.jar in Linux would be %CODE%\HelloWorld\deploy\sca_HelloWorld_rev1.0.jar in Windows. Starting and stopping composites with ant Once you set the environment, you can start up a composite on Linux by running the following command: ant -f ant-sca-mgmt.xml startComposite -Duser=$USERNAME -Dpassword=$PASSWORD -Dhost=$SOAHOST -Dport=$SOAPORT -DcompositeName=HelloWorld -Dpartition=default -Drevision=1.0 Likewise, you can stop a composite on Linux using the following: ant -f ant-sca-mgmt.xml stopComposite -Duser=$USERNAME -Dpassword=$PASSWORD -Dhost=$SOAHOST -Dport=$SOAPORT -DcompositeName=HelloWorld -Dpartition=default -Drevision=1.0 You must also specify the composite name, the partition name it is deployed to, and the revision of the composite you wish to start up and shut down. Packaging, deploying, and undeploying composites with ant The commands in the following sections demonstrate how to package the HelloWorld composite project. This creates a deployable JAR file under the project's ~/deploy subdirectory. This JAR file can then either be manually deployed via Oracle Enterprise Manager Fusion Middleware Control as we have demonstrated earlier in this chapter, or through ant as shown in this section. Packaging a composite via ant The process of packaging a composite is equivalent to using the Make command in JDeveloper. The composite project is validated, compiled, and eventually built into a single deployable JAR file. To package the HelloWorld composite application in Linux, simply run: ant -f ant-sca-package.xml package -DcompositeDir=$CODE/HelloWorld -DcompositeName=HelloWorld -Drevision=1.0 If no errors are encountered, you should expect to find the sca_HelloWorld_rev1.0.jar under the $CODE/HelloWorld/deploy directory. Deploying a composite via ant Now that the composite application is packaged, the SAR (or JAR file) can be deployed. The ant command references the path to the SAR directly (in Linux) as shown: ant -f ant-sca-deploy.xml deploy -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -DsarLocation=$CODE/HelloWorld/deploy/sca_HelloWorld_rev1.0.jar -Dpartition=default -Doverwrite=true -DforceDefault=true As shown in these examples, the server URL, username, and password to the Oracle SOA Suite 11g runtime environment must be supplied. The fully qualified path to the SAR file must be provided in the sarLocation argument. Similar to deploying to the console, you must specify the partition to which you want to deploy. If a partition is not specified then the composite is deployed to the default partition. In this example, you can see that we do not provide a revision for the composite. This is because the revision was already specified during compilation (that is, packaging) time. The overwrite argument specifies if you want to overwrite the composite already deployed to the server and the forceDefault argument specifies if you want this revision to be set as the default revision once it is deployed. The overwrite flag has to be specified if the composite is already deployed with the same revision number in the same partition. For first time deployments, specifying the overwrite flag is optional. Undeploying a composite via ant A composite can be undeployed via ant as well. On Linux, this is done by simply running the following command: ant -f ant-sca-deploy.xml undeploy -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -DcompositeName=HelloWorld -Dpartition=default -revision=1.0 Exporting MDS artifacts with ant The MDS, or Metadata Store, is a database-based repository, which stores various artifacts that can be referenced from within your SOA code. This can include shared schemas (that is, XSD files), WSDLs, fault policies and bindings, domain value maps (DVMs), configuration files, and more. Often, it is necessary to export the contents of the MDS either for backup, export, or management purposes. Fortunately, Oracle has provided an ant target that allows the easy export of MDS contents into a single JAR file. Once the JAR file is exported, it can be unzipped to your local filesystem and browsed through any file browser. This command demonstrates how to execute ant to export the contents of your entire MDS to a single JAR file: ant -f ant-sca-deploy.xml exportSharedData -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -DjarFile=SOAMetaData.jar -Dpattern=** The JAR file SOAMetaData.jar can now be unzipped and browsed through the filesystem. When extracted to a temporary folder such as /tmp/svn, it may extract the following files: /tmp/svn/SOAMetaData/faultPolicies/fault-bindings.xml /tmp/svn/SOAMetaData/faultPolicies/fault-policies.xml These files can now be navigated through the filesystem. The pattern argument can be used to filter the contents you wish to export, allowing you to pick and choose what you want to export if you choose not to export the entire MDS content. For example, specifying a pattern of /apps/SOAMetaData/dvm/**;/apps/SOAMetaData/faultPolicies/** will only export the artifacts under those two subfolders within the MDS. Importing artifacts to the MDS with ant Since MDS artifacts and contents are exported as a JAR file, it makes sense for it to be imported in the same manner. For example, you may have the following files that you just updated on your local file system and wish to import them to the MDS. This may include fault policies, DVMs, and schemas located in the following local directory structure: /tmp/svn/tmp/svn/SOAMetaData/faultPolicies/fault-bindings.xml /tmp/svn/SOAMetaData/faultPolicies/fault-policies.xml /tmp/svn/SOAMetaData/dvm/CurrencyCode.dvm /tmp/svn/SOAMetaData/xsd/ErrorHandling/errorEvent.xsd Firstly, you should zip up the contents of the ~/SOAMetaData subfolder generating a single SOAMetaData.jar file: cd /tmp/svn zip -r SOAMetaData.jar SOAMetaData The JAR file is now ready to be imported to the MDS to maintain the same directory structure inside the MDS: ant -f ant-sca-deploy.xml deploy -Dwl_home=/u01/app/middleware/wlserver_10.3 -Doracle.home=$ORACLE_HOME -DserverURL=$SOAURL/soa-infra/deployer -Duser=$USERNAME -Dpassword=$PASSWORD -Doverwrite=true -DforceDefault=true -DsarLocation=SOAMetaData.jar