5 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. Also, custom hosting applications are generally seeded with metadata that is packaged and deployed to the metadata repository when the application is deployed. Ant-based scripts that generate custom hosting applications do not provide a way to create metadata artifacts. For that reason, after you generate a hosting application, you must open the workspace (.jws) in Oracle JDeveloper, and add the necessary metadata before you deploy the application into the server.

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:

5.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.

  1. Create a hosting application that can execute jobs. Use the create-user-home in the included build.xml file.

  2. Create a JDeveloper project workspace through which you can edit application artifacts with the IDE. This is done when you create the hosting application.

  3. Create an Ant build file with targets for building and deploying parts of the application.

  4. 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.

  5. Package the implemented Java job as a shared library. Use the package_essjob_library target in the generated build.xml file.

  6. Deploy the shared library to the hosting application. Use the deploy_essjob_library target in the generated build.xml file.

  7. Package the hosting application. Use the package_hosting_app target in the generated build.xml file.

  8. Deploy the hosting application. Use the deploy_hosting_app target in the generated build.xml file.

5.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.

5.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/oracle_common/ess/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 5-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 5-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.


5.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 are generated within a JDeveloper-compatible workspace in the target directory you specified. The created workspace has 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 5-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 are found relative to this directory.

This feature relies on the ojdeploy utility to create, package and deploy artifacts to the server. If the middleware home path does not contain an Oracle JDeveloper directory with ojdeploy in the bin directory, specify the directory where Oracle JDeveloper is installed.

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 runtime, 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 is the location of the JDeveloper workspace, where artifacts such as the build.xml file you use later is created.


To create a hosting application with Ant

  1. 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/oracle_common/ess/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.

    [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] Do you want to add shared library for the (java) job business
    logic? (use_jobdef_library) (default=yes)
        [input]      ([yes], no)
    no
    [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 9 files to
    /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
         [copy] Copied 15 empty directories to 4 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: 49 seconds 
    
    [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] Do you want to add shared library for the (java) job business
    logic? (use_jobdef_library) (default=yes)
        [input]      ([yes], no)
    yes
        [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 11 files to
    /scratch/WLServers/MW_HOME/standalone_apps/NewDemoApp
         [copy] Copied 25 empty directories to 9 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 32 seconds 
    

5.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 is in the build file generated when you created a new hosting application. (For more information, see 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 5-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:

  1. 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.

    [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
    
  2. 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 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 5-1 shows what the generated code looks 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 5-1 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);
    }
}

5.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 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
    

5.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 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
    

5.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 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 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
    

5.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 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 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
    

5.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 5-5 to customize the Ant targets with configuration values of your own.


Table 5-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

-

ess.server.name

Comma separated names of Oracle Enterprise Scheduler admin/managed servers to which the Oracle Enterprise Scheduler job library and hosting application is deployed.

weblogic.admin.user

The WebLogic Server admin user name.

weblogic.server.host

-

weblogic.server.port

-

weblogic.server.ssl.port

-

weblogic.t3.url

-


# 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.example.com
WEBLOGIC_HOME=${fmw.home}/wlserver_10.3
weblogic.server.host=adc2170657.example.com
weblogic.server.port=7001
weblogic.server.ssl.port=7002
weblogic.admin.user=weblogic
weblogic.t3.url=t3://${weblogic.server.host}:${weblogic.server.port}
# Comma separated names of ess admin/managed servers to which essjob library and    hosting app is deployed
ess.server.name=AdminServer