Ant tasks are available for most of the command-line interface (CLI)
commands. The tasks are packaged in the ant-javacloud.jar in the SDK.
Each Ant task supports all of the arguments available
in the corresponding CLI command. In addition to those arguments, they also support
additional attributes that provide more control to the ant-build.
All tasks are already defined in antlib.xml located at oracle/javacloud/antlib.xml
in the ant-javacloud.jar.
They can be declared against the namespace prefix of javacloud with the
following snippet.
Note: SDK_HOME points to the SDK home directory.
For example: /Users/javacloud-user/Desktop/work/sdk/oracle-javacloud-sdk
<project name="sample-how-to-use-ant" default="all" basedir="."
xmlns:javacloud="antlib:oracle.javacloud.antlib">
<!--
When you execute the build file, make sure that the Ant properties are available to the build.
(For example: pass -DSDK_HOME=/Users/javacloud-user/Desktop/work/sdk/oracle-javacloud-sdk)
.
.
-->
<property environment="env"/>
<property name="SDK_HOME" value="${env.SDK_HOME}"/>
<path id="javacloud.classpath">
<pathelement location="${SDK_HOME}/lib/ant-javacloud.jar"/>
</path>
<taskdef uri="antlib:oracle.javacloud.antlib" resource="oracle/javacloud/antlib.xml"
classpathref="javacloud.classpath">
<!--
The local.classpath definition is required only when working against a local WebLogic domain.
It can be completely ignored if the build file is aimed to be run only against Oracle Cloud
Note: WEBLOGIC.JAR points to ${WL_HOME}/server/lib/weblogic.jar
-->
<path id="local.classpath">
<pathelement path="${SDK_HOME}/lib/localextension.jar"/>
<!-- optional for running whitelist validation automatically while installing -->
<pathelement path="${SDK_HOME}/lib/whitelist.jar"/>
<pathelement path="${WEBLOGIC.JAR}"/>
</path>
</project>
| Task | Corresponding CLI Command | Additional Ant Attributes (Maven supports these properties) |
|---|---|---|
| <javacloud:install/> | install | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:delete/> | delete | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:update/> | update | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:start/> | start | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:stop/> | stop | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:job-status/> | job-status | failonerror, password, truststorepassword, waitfor, jobstatusproperty, lastlogproperty, timeoutsecs, pollintervalmillis, downloadlastlogonfailure, downloadlastlogpath |
| <javacloud:list-jobs/> | list-jobs | failonerror, password, truststorepassword |
| <javacloud:list-job-logs/> | list-job-logs | failonerror, password, truststorepassword,lastlogproperty |
| <javacloud:job-log-file/> | job-log-file | failonerror, password, truststorepassword |
| <javacloud:list-applications/> | list-applications | failonerror, password, truststorepassword, applicationnamesproperty |
| <javacloud:describe-application/> | describe-application | failonerror, password, truststorepassword, applicationexistproperty,applicationstatusproperty,applicationurlproperty |
| <javacloud:install-library/> | install-library | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:update-library/> | update-library | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:delete-library/> | delete-library | failonerror, password, truststorepassword, jobidproperty |
| <javacloud:list-libraries/> | list-libraries | failonerror, password, truststorepassword, librarynamesproperty |
| <javacloud:list-service-instances/> | list-service-instances | failonerror, password, truststorepassword |
| <javacloud:describe-service-instance/> | describe-service-instance | failonerror, password, truststorepassword, serviceinstancestatusproperty, serviceinstancesizeproperty, dbserviceinstanceproperty |
| <javacloud:restart-service-instance/> | restart-service-instance | failonerror, password, truststorepassword |
| <javacloud:query-service-logs/> | query-service-logs | failonerror, password, truststorepassword |
| <javacloud:query-service-metrics/> | query-service-metrics | failonerror, password, truststorepassword |
| <javacloud:fs-shell/> | fs-shell | failonerror, password, truststorepassword |
| <javacloud:config-shell/> | config-shell | failonerror, password, truststorepassword |
| <javacloud:list-service-metrics/> | list-service-metrics | failonerror, password, truststorepassword |
| <javacloud:list-config/> | list-config | failonerror, password, truststorepassword |
| <javacloud:set-config/> | set-config | failonerror, password, truststorepassword |
| Attribute | Description | Default Value | Ouput Type |
|---|---|---|---|
| failonerror | Flag (true/false) to specify whether the Ant build should fail when the task fails. The default value forces <javacloud: job-status/> to not to fail when the job fails, so that the various output attributes, such as lastlogproperty, can be further used in the same build. If you want the Ant build to fail when the task fails, set this attribute to true. | false | |
| password | Password for the user. | ||
| truststorepassword | Password for the truststore. | changeit | |
| jobidproperty | Output attribute that takes the Ant property name that will be set with the job ID when the task succeeds. The value should be a valid Ant property name. For example, if you specify jobidproperty="jobid" after the task is executed, then ${jobid} will contain the ID of the job initiated by the task. | X | |
| jobstatusproperty | Output attribute that takes the Ant property name, which will be set with the job status. The value should be a valid Ant property name. For example, if you specify jobstatusproperty="job-status" after the task is executed, then ${job-status} will contain the status of the job. | X | |
| lastlogproperty | Output attribute that takes the Ant property name, which will be set with the name of the last log file associated with the current job. The value should be a valid Ant property name. For example, if you specify lastlogproperty="lastlog" then after the task is executed, ${lastlog} will contain the name of the last log. You can use this to get the last log name so that the last log can be downloaded using < javacloud: logfile/>. If the job should fail, the last log is expected to contain the reason why. | X | |
| downloadlastlogonfailure | Boolean (true/false) to indicate if the last log file should be automatically downloaded when the job has failed. This is preferred when working against a local WebLogic domain. This is because if the Ant build file exits, then all the jobs are lost against the local WebLogic domain. | false | |
| downloadlastlogpath | Path to the file where the failed log content is to be downloaded. Applicable only when the attribute downloadlastlogonfailure is true. | The name of the last log + ".log" | |
| applicationexistproperty | Output attribute that takes the Ant property name that will be set with "true" when the application exists. If the application does not exist, and if the Ant property does not have the value, the property will not be set with any value. However, if the Ant property has any other value, it will be reset to "false." The value should be a valid Ant property name. For example, if you specify applicationexistproperty="exists" after the task is executed, then ${exists} will be set if the application exists. | X | |
| applicationstatusproperty | Output attribute that will be set with the status of the application. This will be set only if the application exists. | X | |
| applicationurlproperty | Output attribute that will be set with the application URL. This will be set only when the application exists and the application is in the active stage. Note: If the application has more than one Web module, then there is more than one application URL. In such cases, you can pass the comma-separated list of properties that will be set. If more properties are passed than the number of Web modules, those properties are ignored. The given properties are set with URLs in the same order of the Web modules in the application. If fewer properties are passed, only those are set. | X | |
| waitfor | Flag (true/false) to indicate if the task should wait until the job is completed or until the timeout specified at timeoutsecs occurs. | false | |
| timeoutsecs | Timeout, in seconds, to indicate the maximum time the task must wait before returning. A non-positive value will indicate that the task must wait indefinitely until the job is done. It is applicable when waitfor is true. | 600 (10 mins) | |
| pollintervalmillis | The poll interval, in milliseconds, to check if the job is completed. It is applicable when waitfor is true. | 30000 (30 secs) | |
| dbserviceinstanceproperty | The output property that will be set with the database service name that is associated with this service instance. If there are more database associations, a comma-separated list of property names can be specified. | X | |
| serviceinstancesizeproperty | The output property that is set with the size (of the offering) of the service instance. | X | |
| serviceinstancestatusproperty | The output property that is set with the status of the service instance. | X | |
| applicationnamesproperty | The output property that is set with the comma-separated list of application names. | X | |
| librarynamesproperty | The output property that is set with the comma separated list of libraries. Each library will be represented in the format of 'library-name#spec-version@impl-version'. | X |
Tasks that support the attribute "classpath" support the nested <classpath/> to
conveniently specify the classpath.
Note: A task supports the "classpath" attribute when its corresponding command
supports -classpath as an argument.
Java service instance cannot have more than one active job. Tasks that can create a new job may fail when there is already an active job in the service instance. The following tasks can create new job.
The nested <onresourcebusy/> can be used to handle an active job. By default, the above tasks will wait while a job is already running. You can set retrycount="0" if you want the enclosing task to fail when there is already an active job.
| Attribute | Description | Default Value | Ouput Type |
|---|---|---|---|
| retrycount | The number of times the enclosing task will be retried. When the active job completes or fails, if retrycount is greater than 0, then the enclosing job is retried. Note: During a retry, there may be a new active job again. This attribute tells how many times the enclosing task should be retried. Set retrycount="0" when you don't want to retry. If it is 0, the enclosing task will fail when there is already an active job running in the service instance. | 3 | |
| timeoutsecs | Timeout, in seconds, to indicate the maximum time the task must wait for the active job to complete or fail. A non-positive value will indicate that the task must wait indefinitely until the job is done. It is applicable when retrycount > 0. This timeout is per retry. | 600 (10 mins) | |
| pollintervalmillis | The poll interval, in milliseconds, to check if the active job is completed. It is applicable when retrycount > 0. | 30000 (30 secs) |
Note: If the active job times out, then the enclosing task fails without any further retry.
<javacloud:update debug="true" local="${LOCAL}" failonerror="true" adminurl="${ADMIN_URL}"
user="${USER}"password="${PASSWORD}" identitydomain="${IDENTITY_DOMAIN}"
serviceinstance="${SERVICE_INSTANCE}" application="${APP_NAME}" path="${PATH}"
jobidproperty="jobid" adminstate="true">
<classpath refid="local.classpath"/>
<onresourcebusy retrycount="0"/>
</javacloud:update>
You can write one build file and that can be used against a local WebLogic domain and remote Java Cloud Service - SaaS Extension instances. However, care should be taken while writing the build file that can be executed against a local WebLogic domain. For example, if you run <javacloud:install/> to get the job ID, and then run a <javacloud:job-status/>, then you will need to write the build file in such a way that the same Ant classloader is used to invoke both the tasks. The following is the recommended approach:
<target name="deploy">
<javacloud:install local="${LOCAL}" failonerror="true"
adminurl="${ADMIN_URL}" user="${USER}" password="${PASSWORD}"
identitydomain="${IDENTITY_DOMAIN}" serviceinstance="${SERVICE_INSTANCE}"
application="${APP_NAME}"
path="${PATH}" jobidproperty="jobid">
<classpath refid="local.classpath"/>
</javacloud:install>
<echo message="Install job id:${jobid}">
<javacloud:job-status waitfor="true" local="${LOCAL}" failonerror="true"
adminurl="${ADMIN_URL}" user="${USER}"
password="${PASSWORD}" jobid="${jobid}">
<classpath refid="local.classpath"/>
</javacloud:job-status>
</target>
Note: Doing an <antcall/> for checking the job status is not recommended.