3 Using Ant to Generate a Hosting Application

This chapter describes how you can use Ant targets from a build.xml file included with Oracle Enterprise Scheduler to create a hosting application for use with Java jobs.

Using these targets, you can create the application artifacts in an Oracle JDeveloper workspace, create a template for a Java job implementation, and package and deploy both the application and the Java job (as a shared library).

Note that the Ant targets described here do not create a client user interface with which users can interact with the job. To perform client tasks, you can use Fusion Middleware Control or develop a client user interface with Oracle JDeveloper.

When you have created and deployed your application and shared library, you can use JDeveloper or Enterprise Manager to associate metadata with the deployed outputs.

This chapter includes the following sections:

Section 3.1, "Introduction to Generating a Hosting Application with Ant"
Section 3.2, "Ant Targets for Creating and Deploying a Hosting Application"
Section 3.3, "Creating a Hosting Application and Project Workspace with Ant"
Section 3.4, "Creating a Java Job as a Shared Library with Ant"
Section 3.5, "Packaging a Java Job as a Shared Library with Ant"
Section 3.6, "Deploying a Shared Library with Ant"
Section 3.7, "Packaging a Hosting Application with Ant"
Section 3.8, "Deploying a Hosting Application with Ant"
Section 3.9, "Configuring the Generated Ant Targets"

3.1 Introduction to Generating a Hosting Application with Ant

Oracle Enterprise Scheduler includes an Ant build file through which you can generate the basic artifacts you'll need to get a hosting application running, along with a Java job you can deploy to be executed by the application.

You use the included Ant build file to generate a hosting application. When you do, you also generate another Ant build file that contains targets you can use to generate artifacts for a Java job, as well as to build and deploy the generated components.

When you have created and deployed your application and shared library, you can use JDeveloper or Enterprise Manager to associate metadata with the deployed outputs.

You can also use a generated build.properties file to customize the work Ant does by setting values for variables a target uses when it runs.

The steps described in this chapter include the following you can do with Ant.

Create a hosting application that can execute jobs. Use the create-user-home in the included build.xml file.
Create a JDeveloper project workspace through which you can edit application artifacts with the IDE. This is done when you create the hosting application.
Create an Ant build file with targets for building and deploying parts of the application.
Create a Java job template to which you can add business logic. Use the create-new-job-def target in the generated build.xml file.
Package the implemented Java job as a shared library. Use the package_essjob_library target in the generated build.xml file.
Deploy the shared library to the hosting application. Use the deploy_essjob_library target in the generated build.xml file.
Package the hosting application. Use the package_hosting_app target in the generated build.xml file.
Deploy the hosting application. Use the deploy_hosting_app target in the generated build.xml file.

3.1.1 Prerequisites for Using the Ant Build Files

Before you get started with the provided and generated build files, make sure you're set up with the following prerequisites:

You must have Ant installed and set up, with the ANT_HOME variable set properly and the PATH pointing to ant's bin directory.
You must install and set up Oracle JDeveloper. Your PATH variable must contain the Oracle JDeveloper bin directory so that the jdev command can be executed from the command prompt.

3.2 Ant Targets for Creating and Deploying a Hosting Application

Oracle Enterprise Scheduler includes an Ant build file to get you started toward deploying a hosting application that can execute jobs. However, you're actually using two build files to finish the job: one that is included with Oracle Enterprise Scheduler and another that is generated by a target in the included build file. The following tables list and describe the targets that are included by default in the two files.

By default, the included build.xml file is located in the Oracle Enterprise Scheduler extensibility_scripts directory. For example, in an Oracle JDeveloper installation, you'll find them in MW_HOME/jdeveloper/extensibility_scripts/build.xml; with installations of products that include Oracle Enterprise Scheduler, you'll probably find them in an ORACLE_HOME/extensibility_scripts directory.

Table 3-1 Ant Targets in the Included Build File

Ant Target	Description
create-user-home	Default target to create a user home.
help-create-user-home	Help on creating a user home.

When you run the create-user-home target from the included build.xml file, one of the target's actions is to create another build.xml file. That file contains the following targets that you can use to create, build and deploy artifacts for your application.

Table 3-2 Ant Targets in the Generated Build File

Ant Target	Description
build_ears	Package the job shared library and the hosting application.
create-new-job-def	Create Java job as a shared library.
deploy	Package and deploy the job library and hosting application.
deploy_essjob_library	Deploy the Java job shared library.
deploy_hosting_app	Deploy the hosting application.
deploy_job_logic	Package and deploy the job shared library.
package_essjob_library	Package the Java job as a shared library.
package_hosting_app	Package the hosting application.

3.3 Creating a Hosting Application and Project Workspace with Ant

You can create a hosting application by running the create-user-home Ant target in the build.xml file included with Oracle Enterprise Scheduler.

After the script completes successfully, you'll have the artifacts for a hosting application that you can package and deploy. The artifacts will be generated within a JDeveloper-compatible workspace in the target directory you specified. The created workspace will have a build.xml that you can use to build, package and deploy the hosting application and the generated Java job as a shared library.

As the target runs, you'll be prompted to enter details that guide the target's work. These details include the environment for which the target's work is intended (such as to run with a particular application), the new application's name and target directory, and so on.

Before you get started, you should have in hand the following information for which you'll be prompted by the Ant target:

Table 3-3 Information Needed by the Ant Target

Input Prompt	Description
Which template should be used	Possible values are "Fusion" and "Standalone". If you're developing for use with Oracle Fusion Applications, enter Fusion here. If you're not developing for use with Oracle Fusion Applications, enter "Standalone." There are significant differences between the Oracle Fusion Applications and standalone contexts. For example, in the Oracle Fusion Applications context, the target generates a slightly different hosting application, as well as a client application.
Middleware Home directory path	The Middleware Home directory that was created when Oracle Enterprise Scheduler was installed (probably with another product that embeds it). The locations of supporting libraries will be found as relative to this directory.
Hosting application name	The name you want the new hosting application to have.
Hosting application JPS stripe ID	A stripe is a security construct that defines the subset of values in the policy store that the application intends to use. At run time, it determines which set of policies are applicable for the application. The application name is often used.
Shared library name for job business logic	The name for the shared library into which the generated Java job source code should be placed.
Empty directory where the application will be created	The directory where you want the generated files to go. This will be the location of the JDeveloper workspace, where artifacts such as the build.xml file you'll use later will be created.

To create a hosting application with Ant

To get started, open a console window and change directory to where the included build.xml is located. By default, this is the Oracle Enterprise Scheduler extensibility_scripts directory. For example, in MW_HOME/jdeveloper/extensibility_scripts/build.xml.

Run the target with a command such as the following. You can omit the target name because it is the default target in the build file.

ant

If you want to use the target name, you can do so with the following command.

ant create-user-home

In the following example of Ant console output, note that the prompts begin with the word "[input]". For each prompt, type the value you want to use, then press Enter.

After you've entered the information needed, the target creates the directories and files you requested, copying needed files into your new workspace and setting up some of the configuration for the new hosting application.

Example 3-1 Console Output for the create-user-home Target

[extensibility_scripts]$ ant
 
Buildfile: build.xml
 
-init:
 
create-user-home:
[input] Enter which template should be used (source_template) (default=Fusion)
    [input]      ([Fusion], Standalone)
Standalone
    [input] Enter Middleware Home Directory path (fmw_home_dir) (default=) []
/scratch/fmwtools/mw_home
    [input] Enter hosting application name (hosting_application_name) (default=MyAppEss) [MyAppEss]
NewDemoApp
    [input] Enter hosting application JPS stripe id (hosting_application_stripe_id) (default=MyAppEss) [MyAppEss]
NewDemoApp
    [input] Enter the shared library name for the job business logic (jobdef_library_name) (default=MyJobsLibrary) [MyJobsLibrary]
NewDemoAppJobsLib
    [input] Enter an empty directory where the applications will be created (user_home)
/scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [echo]
     [echo]
    [mkdir] Created dir: /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
[propertyfile] Creating new property file: /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/template.properties
     [copy] Copying 12 files to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [copy] Copied 25 empty directories to 8 empty directories under /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [copy] Copying 1 file to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/ant/config
     [copy] Copying 1 file to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [copy] Copying 15 files to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [move] Moving 1 file to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/Template_Hosting
     [echo]
     [echo] ========================================
     [echo]
     [echo] A new workspace has been created at: /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
     [echo] This workspace can be opened and modified using JDeveloper
     [echo] To deploy the applications, run the following command:
     [echo]     ant -f /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/ant/build-ess.xml deploy
     [echo] To create new jobs from predefined templates, run the following command:
     [echo]     ant -f /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/build.xml create-new-job-def
 
BUILD SUCCESSFUL
Total time: 1 minute 27 seconds

3.4 Creating a Java Job as a Shared Library with Ant

You can create a Java job class template by running the create-new-job-def Ant target that's in the build file generated when you created a new hosting application. (For more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant" for more information.)

The Java class you create here is a template to which you can add logic that implements your Java job. A Java job executes Java code. With the Java job implemented, you can add metadata that comprises some of the specifics for the job.

Note:

Currently, you can create only synchronous Java job templates with this Ant target.

As the target runs, you'll be prompted to enter details that guide the target's work. Before you get started, you should have in hand the following information for which you'll be prompted by the Ant target:

Table 3-4 Information Needed by the Ant Target

Input Prompt	Description
Number of job definition template to create	A number corresponding to the type of Java job implementation you're creating. Currently, only synchronous Java jobs can be created this way, so the only supported value is "1".
Java package name for job definition	The package name for the Java job you're creating.
Java class name for job definition	The class name for the Java job you're creating.

To create a Java job class template with Ant:

To get started, in a console window change directory to the directory you specified as the location to create the application. The build.xml file should be there. Use the following command to run the target:

ant create-new-job-def

In the following example of Ant console output, you can see where the prompts occur. After you've entered that information, the target creates the file you requested, copying needed files into your new workspace and setting up some of the configuration for the new hosting application.

Example 3-2 Console Output of the create-new-job-def Target

[extensibility_scripts]$ ant -f /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/build.xml create-new-job-def

Buildfile: /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/build.xml

-init:

create-new-job-def:
     [echo] Available Job Definition Templates:
     [echo]     1) Simple Synchronous Java Job
    [input] Enter number of job definition template to create (job_template_to_create)
1
     [echo] Calling default target on /scratch/miscFiles/ExtnDemo/extensibility_scripts/Standalone/Template_JobLibrary/simple_synchronous_job/build.xml
 
-init:
 
create-job-definition:
    [input] Enter Java package name for Job Definition (jobdef_package_name) (default=oracle.apps.ess.custom) [oracle.apps.ess.custom]
oracle.apps.ess.custom
    [input] Enter Java class name for Job Definition (jobdef_class_name) (default=MySynchronousJavaJob) [MySynchronousJavaJob]
NewDemoHelloWorld
     [copy] Copying 1 file to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/NewDemoApp/EssSharedLibrary/src
     [copy] Copying 1 file to /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp/NewDemoApp/EssSharedLibrary/src/oracle/apps/ess/custom
 
BUILD SUCCESSFUL
Total time: 34 seconds

Having created the class template for the Java job, you can add code that implements the job's logic. The template is located in project in the JDeveloper workspace you created when you created the hosting application in Section 3.3, "Creating a Hosting Application and Project Workspace with Ant". The file's directory path is shown in the Ant console output. You can use the editor you prefer for editing Java code, such as JDeveloper or a simple text editor.

Open the Java file and add code to implement the execute() method. Example 3-3 shows what the generated code will look like. You would replace the simple implementation of the oracle.as.scheduler.Executable interface's execute() method with code that does your Java job's work.

Example 3-3 Oracle Enterprise Scheduler HelloWorld Java Class

package oracle.apps.ess.custom;

import java.io.StringWriter;
import java.security.AccessControlContext;
import java.security.AccessController;
import javax.security.auth.Subject;

import oracle.as.scheduler.RequestParameters;
import oracle.as.scheduler.job.BaseSynchronousJavaJob;
import oracle.as.scheduler.request.ContentType;
import oracle.security.jps.util.SubjectUtil;

public class NewDemoHelloWorld extends BaseSynchronousJavaJob {

    public NewDemoHelloWorld() {
        super();
    }

    protected void execute() throws Exception 
    {
        long requestId = getRequestExecutionContext().getRequestId();
        RequestParameters params = getRequestParameters();
        AccessControlContext accContext = AccessController.getContext();
        Subject subject = Subject.getSubject(accContext);
        String username = SubjectUtil.getUserName(subject);          
       /*
        * Write contents to request log
        */
        StringWriter strWriter = new StringWriter();
        strWriter.write("Simple ESS Java job execution LOG");
        strWriter.write("ESS Job requestID: " + requestId);
        strWriter.write("Username: " + username);
        writeToRequestLog(requestId, strWriter.toString());

       /*
        * Write Text contents to request output 
        */
        strWriter = new StringWriter();
        strWriter.write("Simple ESS Java job execution Text Out");
        strWriter.write("ESS Job requestID: " + requestId);
        strWriter.write("Username: " + username);
        writeToRequestOutput(requestId, strWriter.toString(), ContentType.Text);
    }
}

3.5 Packaging a Java Job as a Shared Library with Ant

You can package a Java job implementation by running the package_essjob_library Ant target.

Note:

The build file containing this target is generated when you create a new hosting application. (For more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant".)

The package_essjob_library target compiles and JARs the job code. The target simply runs to completion, requiring no user input.

To package a Java job class implementation with Ant:

In a console window change directory to the directory you specified as the location to create the hosting application. Use the following command to run the target:
```
ant package_essjob_library
```

3.6 Deploying a Shared Library with Ant

You can deploy a Java job shared library by running the deploy_essjob_library Ant target.

Note:

The build file containing this target is generated when you create a new hosting application. (For more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant".)

The deploy_essjob_library target deploys the job library. The target simply runs to completion, requiring no user input.

To deploy a Java job shared library with Ant:

In a console window change directory to the directory you specified as the location to create the hosting application. Use the following command to run the target:
```
ant deploy_essjob_library
```

3.7 Packaging a Hosting Application with Ant

You can package a hosting application by running the package_hosting_app Ant target.

Note:

The build file containing this target is generated when you create a new hosting application. (For more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant".)

The package_hosting_app target packages the hosting app created with the create-user-home target (for more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant"). The target simply runs to completion, requiring no user input.

To package a hosting application with Ant:

In a console window change directory to the directory you specified as the location to create the hosting application. Use the following command to run the target:
```
ant package_hosting_app
```

3.8 Deploying a Hosting Application with Ant

You can deploy a hosting application by running the deploy_hosting_app Ant target.

Note:

The build file containing this target is generated when you create a new hosting application. (For more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant".)

The deploy_hosting_app target deploys the hosting app created with the create-user-home target (for more information, see Section 3.3, "Creating a Hosting Application and Project Workspace with Ant"). This target simply runs to completion, requiring no user input.

To deploy a hosting application with Ant:

In a console window change directory to the directory you specified as the location to create the hosting application. Use the following command to run the target:
```
ant deploy_hosting_app
```

3.9 Configuring the Generated Ant Targets

The file <user_home>/ant/config/ess-build.properties contains various parameters to specify information used by the Ant scripts during build, packaging and deployment. The <user_home> is the directory specified to contain the application workspace in step 1 above.

Before deployment of archives, the weblogic server based details has to be changed appropriate to the user's environment.

Use the build properties described in <table> to customize the Ant targets with configuration values of your own.

Table 3-5 Build Properties for Customizing Ant Builds

Build Property	Description
customEss.hostapp.earprofile
customEss.hostapp.jarfile
customEss.hostapp.jarprofile
customEss.hostapp.jprproject
customEss.hostapp.jwsfile
customEss.hostapp.mds.jdbc
customEss.hostapp.mds.partition
customEss.hostapp.name	The name to be used for the generated hosting application.
customEss.hostapp.workspace
customEss.project.dir	The directory location for the generated JDeveloper project.
customEss.shared.library.name	The name to be given to the generated shared library.
ess.script.base.dir
fmw.home
jdev.home
oracle.common
weblogic.admin.password	The WebLogic Server admin password.
weblogic.admin.user	The WebLogic Server admin username.
weblogic.server.host
weblogic.server.port
weblogic.server.ssl.port
weblogic.t3.url

Example 3-4 Contents of an ess-build.properties File for Configuring Ant Builds

# ESS build properties
ess.script.base.dir=${user_home}
 
fmw.home=${fmw_home}
jdev.home=${fmw.home}/jdeveloper
oracle.common=${fmw.home}/oracle_common
 
# ========== ESS JDev project details ===============
customEss.project.dir=${ess.script.base.dir}
 
customEss.hostapp.workspace=${hosting_application_name}
customEss.hostapp.jwsfile=${hosting_application_name}
customEss.hostapp.earprofile=${hosting_application_name}
customEss.hostapp.jprproject=EssSharedLibrary
customEss.hostapp.jarprofile=EssSharedLibrary
customEss.hostapp.jarfile=${jobdef_library_name}
 
customEss.shared.library.name=${jobdef_library_name}
 
customEss.hostapp.mds.partition=${hosting_application_name}
customEss.hostapp.mds.jdbc=mds-ESS_MDS_DS
customEss.hostapp.name=${hosting_application_name}
 
# ========== Weblogic Server details ===============
MW_HOME=${fmw.home}
ORACLE_HOME=${jdev.home}
MW_ORA_HOME=${jdev.home}
COMMON_COMPONENTS_HOME=${oracle.common}
WEBLOGIC_HOME=${fmw.home}/wlserver_10.3
weblogic.server.host=adc2170657.us.oracle.com
WEBLOGIC_HOME=${fmw.home}/wlserver_10.3
weblogic.server.host=adc2170657.us.oracle.com
weblogic.server.port=7001
weblogic.server.ssl.port=7002
weblogic.admin.user=weblogic
weblogic.admin.password=welcome1
weblogic.t3.url=t3://${weblogic.server.host}:${weblogic.server.port}