5 Programming BI Scheduler Java Jobs

This chapter explains that you can use the Oracle BI Scheduler to schedule Java programs, called Java jobs, that extend the functionality of Oracle Business Intelligence. Java jobs can be either standalone Scheduler Jobs in Job Manager (Windows), or existing Java Actions in Oracle BI Delivers that are added to the end of agents and upgraded from Release 10g (Windows or UNIX).

Note that existing Java actions that are upgraded from Release 10g can be executed, but not created in Release 11g. Instead, you should use the EJB-based Java actions that are available in this release. For more information on actions, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

This chapter describes programming Java jobs for the Oracle BI Scheduler and contains the following topics:

5.1 Using Oracle BI Scheduler Java Jobs

Java jobs are Java programs that are executed by the JavaHost process on behalf of the Oracle BI Scheduler. Java jobs are different than Java EJB actions. A Java job is deployed in a JAR file, with the entry point defined by one class. That class must implement the SchedulerJavaExtension interface. The job's context is provided by the input SchedulerJobInfo parameter.

This section contains the following information:

5.1.1 Adding and Configuring Custom Java Jobs in Job Manager

You add and configure custom Java jobs in the Modify Job and Add Jobs dialog boxes in Job Manager. Refer to Section 3.2, "Adding Oracle BI Scheduler Jobs in Job Manager", and Section 3.3, "Modifying Oracle BI Scheduler Jobs in the Job Manager".

Note:

The Java program must exist on the Oracle BI Scheduler server computer before you can create the job in Job Manager. Create the Java program, and then create the job to call the Java program.

To configure and add custom Java jobs in Job Manager:

  1. Set the custom properties according to the descriptions in Section 6.4, "Job Action Properties Available in Job Manager".

  2. In the Add New Job window, enter the properties.

    For example, for the Java program filecopy.jar, use the values that are shown in the following table. To view an example of the filecopy.jar program, see Section 5.1.2, "Example: Creating a Java Program for Agents".

    Field Value or Setting

    Script Type

    Java

    Class Name

    sched.sched

    The Java class that you created in Section 5.1.2, "Example: Creating a Java Program for Agents."

    Class Path

    filecopy.jar

    The JAR file that contains the Java class.

    Parameters

    c:\tmp\report.pdf

    Note: The owner of the JavaHost process must have write permissions on this directory point.


  3. Click OK.

    The Java program is run after the Conditional Request of the agent is run.

    You cannot add a new Java job action to an agent in Oracle BI Delivers. You can use only existing ones that have been upgraded to this release. However, you can add a new Java job to a job in Job Manager. For information, see Section 3.2, "Adding Oracle BI Scheduler Jobs in Job Manager."

5.1.2 Example: Creating a Java Program for Agents

This example creates a Java program that copies the results of an agent to another directory. The example creates a Java class that contains filecopy logic.

To create a Java program to be used with agents:

  1. Create a Java program using a Java editor.

    1. Create a new Java class called 'sched'.

    2. Paste the following code into the Java editor:

      package sched;
          import java.io.*;
          import java.lang.Thread;
       
          import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJavaExtension;
          import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJobException;
          import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJobInfo;
       
          public class sched implements SchedulerJavaExtension{
          public void run(SchedulerJobInfo jobInfo) throws SchedulerJobException
          {
            System.out.println("JobID is:" + jobInfo.jobID());
            System.out.println("Instance ID is:" + jobInfo.instanceID());
            System.out.println("JobInfo to string is:" + jobInfo.toString());
            try
            {
              // File outputFile = new File("D:\\JavaJob.txt");
              File attachFile = jobInfo.getResultSetFile();
              
              InputStream in = new FileInputStream(attachFile.getAbsolutePath());
              OutputStream out = new FileOutputStream(jobInfo.parameter(0));          
              byte[] buf = new byte[1024];
              int len;
              while ((len = in.read(buf)) > 0) 
              {
                out.write(buf, 0, len);
              }
              in.close();
              out.close();        
              
            }
          catch(Exception ex)
          {
            throw new SchedulerJobException(1, 1, ex.getMessage());
          }
          }
          public void cancel()
          {
          }
          }
      
    3. Add the schedulerrpccalls.jar file from the \MW_HOME\ORACLE_HOME\bifoundation\javahost\lib\scheduler directory into your classpath.

    4. Compile the Java Class without errors.

    5. Jar the compiled output to a file. For example, filecopy.jar.

    6. Note the location of the file and ensure that there are no errors.

5.1.3 Example: Configuring a Java Program

This example configures the Java program that you created in Section 5.1.2, "Example: Creating a Java Program for Agents" to enable the Java job to work with agents.

To configure a Java program to be used with agents:

  1. Copy the filecopy.jar file that you created in Section 5.1.2, "Example: Creating a Java Program for Agents" to the following directory:

    ORACLE_HOME\bifoundation\javahost\lib

  2. Make the following changes to the JavaHost configuration file, which is called config.xml:

    <Scheduler>
      <Enabled>True</Enabled>       
    <DefaultUserJarFilePath>D:\<ORACLE_HOME>\bifoundation\javahost\lib</DefaultUserJarFilePath>
    </Scheduler>
    

    See "Using the Javahost Service for Oracle BI Presentation Services" Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition for information on working with the JavaHost configuration file.

    If the JavaHost file is not configured correctly, then the agent log file can stop getting written to, although the agent and the Scheduler are still running. In this situation, you stop the Scheduler using the Windows Task Manager.

  3. Restart the JavaHost service.

5.2 Oracle BI Scheduler Java Jobs

The Oracle BI Scheduler integrates with the JavaHost Service to support a custom Java program. The Oracle BI Scheduler provides two Java interfaces (SchedulerJavaExtension and SchedulerJobInfo) and one Java class (SchedulerJobException). You provide a class that implements the SchedulerJavaExtension interface.

Note:

For more information about the JavaHost service, see, "Using the Javahost Service for Oracle BI Presentation Services" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.

5.3 Adding Java Jobs for Oracle BI Scheduler

Use the following procedure to add a Java job for the Oracle BI Scheduler.

Note:

The compiled Java class file has to exist on the JavaHost computer before you can configure the properties.

To add a Java Job for Oracle BI Scheduler:

  1. Access the Job Manager and from the Jobs menu, select Add New Job.

    The Add New job window appears.

  2. In the Script Type field, select Java.

  3. Specify the custom properties. For information about setting these values, see Section 6.4, "Job Action Properties Available in Job Manager".

    Example values and settings for a Java job with the class name "sample.Test", file path "Sample", and no additional paths and parameters are included below.

    Field Value or Setting

    Script Type

    Java

    Class Name

    sample.Test

    Class File (Jar File)

    Sample


  4. Click OK.

5.4 Oracle BI Scheduler Custom Java Program Package

The public interfaces and class for Oracle BI Scheduler Custom Java Program are packaged as com.siebel.analytics.scheduler.javahostrpccalls. There are two interfaces and one class, which are described in following topics:

5.5 SchedulerJavaExtension Interface

Your custom code must implement the following interface:

package com.siebel.analytics.scheduler.javahostrpccalls;
public interface SchedulerJavaExtension {
public void run(SchedulerJobInfo jobInfo) throws SchedulerJobException;
public void cancel();
}

This interface has two methods: run and cancel. The following table describes the methods:

Method Description

run

This method is invoked by the JavaHost. It provides one SchedulerJobInfo object (described below), which contains instance-related properties such as user ID, Job ID, and Instance ID and parameters. The method is declared to throw SchedulerJobException, which is also described below.

cancel

This method is invoked if the Job instance is still running while Scheduler wants to cancel it. The cancel method is called concurrently by a different thread. Your implementation must therefore protect any data that is shared by the run and cancel methods by synchronization blocks. A typical implementation would be to set a 'cancelCalled' boolean in the cancel method implementation, and check this in any long running loops in the run implementation.


5.6 SchedulerJobInfo Interface

The SchedulerJobInfo interface provides information about the currently running job instance to the custom code:

package com.siebel.analytics.scheduler.javahostrpccalls;
import java.io.*;
public interface SchedulerJobInfo {
public final int kJavaJobInformation = 0;
public final int kJavaJobWarning = 1;
public final int kJavaJobError = 2;
int jobID();
int instanceID();
int parameterCount();
String parameter(int index);
boolean hasResultSet();
File getResultSetFile();
String userID();
int getExitCode();
void setExitCode(int exitCode);
int getStatus();
void setStatus(int status);
String getMessage();
void setMessage(String message);
void appendMessage(String message);
}

Three public final integers, kJavaJobInformation, kJavaJobWarning, and kJavaJobError are the suggested values that are used to set the status depending upon the circumstances. The following table describes the circumstances:

Members Description

public final int kJavaJobInformation = 0

Contains an informational message.

public final int kJavaJobWarning = 1

Contains a warning message.

public final int kJavaJobError = 2

Contains an error message.


The following table describes all the methods that are declared in the interface:

Method Description

int jobID()

Returns the job ID that is associated with the agent.

int instanceID()

Returns the instance ID that is associated with the agent.

int parameterCount()

Returns how many parameters are associated with the agent.

String parameter(int index)

Returns the indexed parameter for the agent.(1).

boolean hasResultSet()

Specifies if there is a result set for this agent.

File getResultSetFile()

Returns a file of result set for this agent (2).

String userID()

Returns the ID of the user who is running the agent.

int getExitCode()

Returns the exit code for the agent.

void setExitCode(int exitCode)

User can set the exit code for the agent.

int getStatus()

Returns the status code for the agent.

void setStatus(int status)

User can set the status code for the agent.

String getMessage()

Returns the message that is associated with the agent.

void setMessage(String message)

User can set the message that is associated with the agent. It replaces the existing message.

void appendMessage(String message)

User can append an additional message to the agent.


5.7 SchedulerJobException Class

If your custom code cannot complete successfully, then throw an instance of this exception class.

package com.siebel.analytics.scheduler.javahostrpccalls;
public final class SchedulerJobException extends Exception {
public SchedulerJobException(int exitCode, int status, String message) {
m_exitCode = exitCode;
m_status = status;
m_message = message;
}
public int getExitCode() {
return m_exitCode;
}
public int getStatus() {
return m_status;
}
public String getMessage() {
return m_message;
}
private int m_exitCode;
private int m_status;
private String m_message;
}

The run method of the SchedulerJavaExtension interface is declared to throw SchedulerJobException. The following table describes the three members:

Members Description

int m_exitCode

The framework assigns this exit code to the agent.

int m_status

The framework assigns this status code to the agent.

String m_message

The framework assigns this message to the agent.


5.8 Oracle BI Scheduler Java Extension Example

The following example illustrates how to use the previously described interfaces and class to create a custom Java action. For more information, see Section 5.1, "Using Oracle BI Scheduler Java Jobs."

This example does not contain any long running code, so it is acceptable to do nothing in the cancel method.

When the compiled class runs, it collects the ID of the user who ran the agent, the job ID of the agent, the instance ID of the agent, and all possible parameters into an output file.

package sample;
import java.io.*;
import java.lang.Thread;
import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJavaExtension;
import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJobException;
import com.siebel.analytics.scheduler.javahostrpccalls.SchedulerJobInfo;
/**
 *
 * @author
 */public class SimpleTest implements SchedulerJavaExtension
{
public void run(SchedulerJobInfo jobInfo) throws SchedulerJobException
{
System.out.println("JobID is:" + jobInfo.jobID());
System.out.println("Instance ID is:" + jobInfo.instanceID());
System.out.println("JobInfo to string is:" + jobInfo.toString());
try
{
File outputFile = new File("D:\\temp\\JavaJob.txt");
FileWriter out = new FileWriter(outputFile);
out.write("User ID:\t\t" + jobInfo.userID() + "\r\n");
out.write("Job ID:\t\t" + jobInfo.jobID() + "\r\n");
out.write("Instance ID:\t\t" + jobInfo.instanceID() + "\r\n");
out.write("Parameter Count:\t\t" + jobInfo.parameterCount() + "\r\n");
for(int i = 0; i < jobInfo.parameterCount(); ++i)
{
out.write("\tParameter ");
out.write(new Integer(i).toString());
out.write(":\t" + jobInfo.parameter(i) + "\r\n");
}
out.close();
}
catch(Exception ex)
{
throw new SchedulerJobException(1, 1, ex.getMessage());
}
}
public void cancel()
{
}
}