Automatic deployment .ear file to Oracle Application Server 10.1.3 (OAS) with Ant tasks

In this post I would like to share an example how to deploy an .ear file with an Ant script to the Oracle Application Server 10.1.3 (OAS). Automatic deployment can help improve the release process. First of all because manual deployment usually costs time of the developers. Especially the lead time will be long if the uploading of the .ear file to the  server takes a long time. And mistakes made with manual deployment can cause quite some fixing time.

The Oracle documentation describes the use of Ant tasks for automatic deployment to the OAS. For more information on Ant tasks you can find an URL at the end of this post to the online Oracle documentation for the OAS, version 10.1.3.
Versions 10.1.2 and earlier of the OAS have a different method for automatic deployment of the .ear to the server. This happens through a ‘Oc4jDcmServletAPI’ and will not be discussed here.

Below you will find an example script regarding the use of Ant tasks:

<?xml version=”1.0″ encoding=”windows-1252″ ?>
<project name=”XXX” default=”redeploy” basedir=”.” xmlns:oracle=”antlib:oracle”>
<property name=”ear.dir”  value=”${basedir}”/>

<target name=”stop-app”>
<echo message=”Stopping the application”/>
<oracle:stop deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”/>
</target>

<target name=”start-app”>
<echo message=”Starting the application”/>
<oracle:start deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”/>
</target>

<target name=”undeploy-ear”>
<echo message=”Undeploying the application module deployment (ear) file”/>
<oracle:undeploy deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”
logFile=”${basedir}/undeploy-ear.log”/>
</target>

<target name=”deploy-ear”>
<echo message=”Deploying the application module deployment (ear) file”/>
<oracle:deploy deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” file=”${basedir}/${ear.filename}”
deploymentName=”${app.name}” bindAllWebApps=”default-web-site”
contextRoot=”${context.root}” logFile=”${basedir}/deploy-ear.log”/>
<oracle:bindWebApp deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”
webModule=”${war.filename}” webSiteName=”${oc4j.binding.module}”
contextRoot=”${context.root}”/>
</target>

<target name=”redeploy”>
<input message=”Which release number are you deploying?” addproperty=”ear.version” />
<input message=”To which environment are you deploying? ” addproperty=”deploy.environment”/>

<property name=”ear.location” value=”<repository> /${ear.version}/”/>
<property name=”ear.filename” value=” ear-${ear.version}.ear”/>
<property name=”war.filename” value=”viewController-${ear.version}”/>

<get src=”${ear.location}${ear.filename}” dest=”${basedir}/${ear.filename}”/>

<property file=”deploy_${deploy.environment}.properties”/>

<ant target=”undeploy-ear”/>
<ant target=”deploy-ear”/>
<ant target=”stop-app”/>
<ant target=”start-app”/>

<delete file=”${basedir}/${ear.filename}”/>
</target>
</project>

The code explained

In this example there are a couple of  preconditions. The released ear is to be found in the project repository and needs to be download from there. This example also took into account that you may want to redo a deployment, for example. Therefore the script doesn’t deploy the ear automatically after a build, but you can manually start the script and choose which released ear you want to deploy to which environment.  The following bullets explain the Ant script:

1. The script contains Ant targets per action (stop, start, undeploy, deploy).
2. ‘redeploy’ is the default target if the script is executed. This target actually executes all the steps to reploy the ear on the OAS:
   1. input is asked which version needs to be deployed
   2. input is asked to which environment needs to be deployed
   3. the right ear is downloaded from the repository to the local deployment directory
   4. the current deployment get undeployed from the right OAS
   5. the new ear gets deployed to the right OAS, to the right OC4J instance
   6. the OC4J instance gets stopped
   7. the OC4J instance gets started
   8. the new ear is removed from the deployment directory
3. In  the script properties of the chosen environment are being used, these are collected from the properties file in the deployment directory:

deploy_<environment>.properties:

# The JSR88 deployer URIs. Valid URIs are:
# 1- Oracle Application Server Cluster URI::
#   deployer:cluster:opmn://opmnHost[:opmnPort]/oc4jInstanceName
# 2- Oracle Application Server Single Instance URI:
#   deployer:oc4j:opmn://opmnHost[:opmnPort]/oc4jInstanceName
#   deployer:oc4j:opmn://opmnHost[:opmnPort]/asInstanceName/oc4jInstanceName
# 3- OC4J URI:
#   deployer:oc4j:[host]:[rmiPort]
deployer.uri=deployer:oc4j:opmn://<host>:<6003>/< iASInstanceName>/<OASInstanceName >

# The administrative login name for the target OC4J instance
oc4j.admin.user=oc4jadmin

# The administrative password for the target OC4J instance
oc4j.admin.password=<password>

# The application name within the target OC4J instance
app.name=<application_name>

# The context root of the OC4J application (including the ‘/’)
context.root=/<context-root>

# The web site to which the deployed web modules are bound
oc4j.binding.module=default-web-site

It can be a bit of a search as to fill in the right properties. Therefore I would like to provide some images as a tool to find the right properties in the OAS Enterprise Manager.

Image 1

Image 2

Image 3

When running the Ant script, be aware that the OC4J Ant tasks utilize the ant installation that is shipped with the local JDeveloper 10 installation. For one there has to be a system variable ANT_HOME that points to the ant home in the JDeveloper installation (for example C:\JDeveloperADF10\ant). As a second the system variable PATH needs to contain the path to the ..\ant\bin directory of the local JDeveloper 10 installation (for example C:\JDeveloperADF10\ant\bin). Of course this can also be scripted in the command file to start the Ant script.

Oracle Documentation
De following URL guides you to the Oracle documentation “Oracle® Containers for J2EE Deployment Guide 10g Release 3 (10.1.3)”. This documentation contains a chapter about the method used here: “Deploying with the OC4J Ant Tasks”:

http://docs.oracle.com/cd/B25221_05/web.1013/b14431/toc.htm