Skip Headers

Oracle® Application Server Containers for J2EE Job Scheduler Developer's Guide 10g Release 3 (10.1.3) B15876-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 9 Deploying Job Scheduler-Enabled Applications

This chapter provides information on how to configure Job Scheduler-enabled applications for deployment. The following topics are covered:

- Bundling Job Scheduler with a J2EE Application

- Configuring Persistence for Job Scheduler

- Configuring Security for Job Scheduler

- Configuring Logging for Job Scheduler

- Configuring DMS for Job Scheduler

- Configuring JMX for Job Scheduler

- Configuring Execution Interval Threshold Recovery for Job Scheduler

## 9.1 Bundling Job Scheduler with a J2EE Application

Job Scheduler is deployed as a stateless session Enterprise Java Bean (EJB). Unlike a typical EJB, the actual class files do not need to be deployed with Job Scheduler. Instead, these files are included as part of Oracle Application Server Containers for J2EE (OC4J).

### 9.1.1 Generating the scheduler-ejb.jar File

As is the case with all EJBs, a deployment descriptor is required. For Job Scheduler, there are two:

1. `ejb-jar.xml` (Job Scheduler deployment descriptor)

2. `orion-ejb-jar.xml` (OC4J-specific Job Scheduler deployment descriptor)

Note that both of these files must be present in the `scheduler-ejb.jar` archive file for Job Scheduler to function correctly.

To deploy Job Scheduler with an application, an application deployer needs to include the `scheduler-ejb.jar` archive. In addition to the `ejb-jar.xml` and `orion-ejb-jar.xml` files, this archive must also include the following:

- All job implementations

- All event listener implementations

For Job Scheduler to access job and event listener implementations, the class files must be included in the `scheduler-ejb.jar` archive. It is the application deployer's responsibility to generate this file and bundle it with the application.

Example 9-1 shows a sample `scheduler-ejb.jar` file. A Job Scheduler-enabled application uses the `test.job` job and `test.watch` event listener implementations as part of the application.

Example 9-1 Sample scheduler-ejb.jar File

    test/job.class
    test/watch.class
    META-INF/ejb-jar.xml
    META-INF/orion-ejb-jar.xml

### 9.1.2 Bundling scheduler-ejb.jar in an Enterprise Archive (EAR) File

Once the `scheduler-ejb.jar` file is generated, it must be bundled in the application's EAR file. In addition, the archive's `application.xml` file must contain a module entry for Job Scheduler.

In Example 9-2, Job Scheduler is deployed with a J2EE application. The addition of Job Scheduler to the application is accomplished by adding a `<module>` element as shown in Example 9-2.

Example 9-2 Adding the Job Scheduler to the application.xml File

    <module>
       <ejb>scheduler-ejb.jar</ejb>
    </module>

## 9.2 Configuring Persistence for Job Scheduler

Job Scheduler provides three basic types of persistent job storage:

- In-memory (JMS persistence)

- File-based (JMS persistence)

- Database-backed (JDBC persistence)

To configure JMS persistence, set the `jobStoreProviderClassName` `<env-entry>` to `oracle.ias.scheduler.core.jobstore.jdbc.ProvderImpl`. In-memory or file-based persistence is achieved by configuring JMS queues to be in-memory or file-based, respectively.

To configure database-backed persistence, run the `J2EE_HOME``/database/scheduler_jobstore.sql` script to create the database tables, set the `jobStoreProviderClassName` `<env-entry>` to `oracle.ias.scheduler.core.jobstore.jdbc.ProviderImpl`.

Examples of how to configure both JDBC and JMS persistence are provided in the following sub-sections.

### 9.2.1 Configuring JDBC Persistence

To configure JDBC persistence:

1. Run the `scheduler_jobstore.sql` SQL script to create the database tables.

2. In the `ejb-jar.xml` file, set the `jobStoreProviderClassName` <`env-entry>` value as follows:

       <env-entry>
          <env-entry-name>jobStoreProviderClassName</env-entry-name>
          <env-entry-type>java.lang.String</env-entry-type>
          <env-entry-value>
             oracle.ias.scheduler.core.jobstore.jdbc.ProviderImpl</env-entry-value>
       </env-entry>

3. Create a new `<managed-data-source>` entry in `data-sources.xml`, making sure that the specified connection pool references an existing `<connection-pool>`:

       <managed-data-source name="SchedulerJobstore"
                             connection-pool-name="Example Connection Pool"
                             jndi-name="scheduler/jobstore" />

For a complete example on configuring JDBC persistence, refer to the following How-To located on OTN:

`http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-scheduler-db/doc/readme.html`

### 9.2.2 Configuring JMS Persistence

To configure JMS persistence:

1. In the `ejb-jar.xml` file, set the `jobStoreProviderClassName` `<env-entry>` value as follows:

       <env-entry>
          <env-entry-name>jobStoreProviderClassName</env-entry-name>
          <env-entry-type>java.lang.String</env-entry-type>
          <env-entry-value>
             oracle.ias.scheduler.core.jobstore.jms.ProviderImpl
          </env-entry-value>
       </env-entry>

2. In the `jms.xml` file, create a new `<queue>` entry as shown below:

       <queue name="jms/scheduler_jobstore"
               persistence file="scheduler_jobstore">
          <description>scheduler job store queue</description>
       </queue>

The queue destinations defined in `jms.xml` are persistent only if the `persistence-file` attribute on each queue destination is set. Please refer to the JMS documentation for more information about creating a persistent queue destination.

For a complete example on configuring JMS persistence, refer to the following How-To located on OTN:

`http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-scheduler-jms/doc/readme.html`

## 9.3 Configuring Security for Job Scheduler

Job Scheduler's `ejb-jar.xml` deployment descriptor file contains information about the security configuration for Job Scheduler. This information can be modified to limit access to one or more of Job Scheduler APIs to a specific role. For example, removing a job can be limited to users with administrative privileges.

In Example 9-3, application users are divided into two general categories: users and administrators. Users can only submit jobs, while administrators can submit, pause, resume, cancel, and remove jobs.

Example 9-3 Two-Tier Security Model

    <!-- role declarations -->
    <security-role>
      <role-name>user</role-name>
    </security-role>

    <security-role>
      <role-name>administrator</role-name>
    </security-role>

    <!—- methods that can be invoked by the group 'user' -->
    <method-permission>
      <role-name>user</role-name>

      <method>
        <ejb-name>scheduler</ejb-name>
        <method-name>add</method-name>
      </method>
    </method-permission>

    <!—- methods that can be invoked by the group 'administrator' -->
    <method-permission>
      <role-name>administrator</role-name>
      <method>
        <ejb-name>scheduler</ejb-name>
        <method-name>remove</method-name>
      </method>

      <method>
        <ejb-name>scheduler</ejb-name>
        <method-name>pause</method-name>
      </method>

      <method>
        <ejb-name>scheduler</ejb-name>
        <method-name>resume</method-name>
      </method>

      <method>
        <ejb-name>scheduler</ejb-name>
        <method-name>cancel</method-name>
      </method>
    </method-permission>

## 9.4 Configuring Logging for Job Scheduler

This section discusses the available log level settings for Job Scheduler. The root logger has a default log level set to `Level.WARNING`, since unexpected and fatal errors will be logged by the root logger. However, the log level can be changed by setting the string value of the `<env-entry>` called `globalLogLevel` in the `ejb-jar.xml` file, as shown in Example 9-4.

Example 9-4 Changing the Log Level

    <env-entry>
       <env-entry-name>globalLogLevel</env-entry-name>
       <env-entry-type>java.lang.String</env-entry-type>
       <env-entry-value>FINEST</env-entry-value>
    </env-entry>

Table 9-1 shows the mapping between the `<env-entry>` values and the corresponding log levels to which they match.

Table 9-1 <env-entry> Values and Log Levels

<env-entry> Value | Log Level
--- | ---
`OFF` | `Level.OFF`
`FINEST` | `Level.FINEST`
`FINER` | `Level.FINER`
`FINE` | `Level.FINE`
`CONFIG` | `Level.CONFIG`
`INFO` | `Level.INFO`
`WARNING` | `Level.WARNING`
`SEVERE` | `Level.SEVERE`
`ALL` | `Level.ALL`

## 9.5 Configuring DMS for Job Scheduler

To configure whether or not DMS statistics are published, set the `<env-entry>` value in the `ejb-jar.xml` file as shown in Example 9-5.

Example 9-5 Configuring DMS

    <env-entry>
       <env-entry-name>oracle.ias.scheduler.dms</env-entry-name>
       <env-entry-type>java.lang.String</env-entry-type>
       <env-entry-value>true</env-entry-value>
    </env-entry>

The `<env-entry-value>` is set to true, meaning DMS statistics will be published. Set this value to false if you do not want DMS statistics published.

## 9.6 Configuring JMX for Job Scheduler

To configure whether or not JMX MBeans are published, set the `<env-entry>` value in the `ejb-jar.xml` file as shown in Example 9-6.

Example 9-6 Configuring JMX

    <env-entry>
       <env-entry-name>oracle.ias.scheduler.jmx</env-entry-name>
       <env-entry-type>java.lang.String</env-entry-type>
       <env-entry-value>true</env-entry-value>
    </env-entry>

The `<env-entry-value>` is set to true, meaning JMX MBeans will be published. Set this value to false if you do not want JMX MBeans published.

## 9.7 Configuring Execution Interval Threshold Recovery for Job Scheduler

Some job executions might be scheduled during the time when the container has been shutdown. The Job Scheduler provides the ability to recover these missed executions. One or more executions scheduled during the time the container is down will result in one job execution when the container starts up.

In the case of fixed-interval and fixed-delay schedules, it is possible to enable execution recovery for jobs whose repetition interval is greater than a configurable execution recovery threshold duration.

To do so, set the `<env-entry>` value with the desired threshold value in minutes, as shown in Example 9-7. If this value is not set, the value defaults to 30 minutes. Job execution recovery is performed only for fixed-interval and fixed-delay jobs executing at intervals greater than 30 minutes.

Example 9-7 Configuring Execution Threshold Recovery

    <env-entry>
       <env-entry-name>intervalThresholdMinutes</env-entry-name>
       <env-entry-type>java.lang.Long</env-entry-type>
       <env-entry-value>35</env-entry-value>
    </env-entry>