6 Job Scheduler

The following sections describe how you can manage the job engine and schedule jobs through the Mobile Manager.

Section 6.1, "Scheduling a Job to Execute at a Specific Time or Interval"
Section 6.2, "Managing the Job Engine"
Section 6.3, "Manage Scheduled Jobs Using the Mobile Manager"
Section 6.4, "Managing Scheduled Jobs Using ConsolidatorManager APIs"
Section 6.5, "Using the ConsolidatorManager APIs to Create Jobs"

6.1 Scheduling a Job to Execute at a Specific Time or Interval

You can choose to execute any job—which can be any application—at a specific time or interval. For example, the default MGP process (see Section 5.1, "How Does the Synchronization Process Work?") is a job that executes at a regular interval. The default behavior is for the MGP process to execute every 60 seconds to apply all incoming modifications from the clients and compose all outgoing messages to the clients from the repository. You can define how often the MGP process executes, or even schedule a time for it to stop execution. You can schedule any job with this same mindset.

Note:

For an overview on how to create a job out of one of your applications, see Section 6.5, "Using the ConsolidatorManager APIs to Create Jobs".

The engine that monitors the job execution is the Job Scheduler. For example, by default, the Job Scheduler fires off the MGP process every 60 seconds. It is the mechanism that tracks all of the scheduled jobs and ensures that your defined job is executed when you wanted it to be executed. You can turn it on and off, and monitor alerts specific to the Job Scheduler.

See Section 6.2, "Managing the Job Engine" for details on how to manage the job engine; see Section 6.3, "Manage Scheduled Jobs Using the Mobile Manager" on how to create and manage jobs that you want scheduled.

Note:

Within the OC4J or Web-to-Go client, you can also schedule when a synchronization is started on the client. This is separate from the Mobile Server Job Scheduler. See Section 2.3.1.1.2, "Configuration Tab" for more information.

6.2 Managing the Job Engine

The Job Scheduler manages jobs that you create and schedule. However, the Job Scheduler needs to be managed, as well. You navigate to the Job Scheduler page in the Mobile Manager by selecting a Mobile Server from the list of Mobile Servers on the Mobile farm screen. At the bottom of the Mobile Server screen, click Job Scheduler, which brings up the Home screen for the Job Scheduler.

The following sections describe how to manage the Job Scheduler:

Section 6.2.1, "Starting the Job Scheduler"
Section 6.2.2, "Checking Job Scheduler Alerts"
Section 6.2.3, "Managing Active Jobs"
Section 6.2.4, "Managing the Job History List"

6.2.1 Starting the Job Scheduler

Figure 6-1 displays the Job Scheduler's default status on the Job Scheduler home page. To start the Job Scheduler, click Start. At this stage, the "Start" button is replaced by the "Stop" button. The following image displays that the Job Scheduler is up and running.

Figure 6-1 The Job Scheduler Home Page

Description of "Figure 6-1 The Job Scheduler Home Page"

To stop the Job Scheduler, click Stop. Stopping the Job Scheduler prevents any new jobs from starting. However, any existing jobs will continue to execute until finished. Stopping the Job Scheduler does not kill any existing jobs. If you want to prevent only a single job from being launched, then disable the application on the Administration screen. See Section 6.3.3, "Enabling or Disabling Jobs" for more information on disabling applications.

6.2.2 Checking Job Scheduler Alerts

When the Job engine fails, then the Alerts table displays these exceptions as critical alerts. When the Job engine has trouble with executing your job, then these exceptions are displayed as warning alerts.

The Job Scheduler home page enables administrators to check alerts that are registered in the job engine. To check alerts, locate the "Alerts" table and select the alert that you need to view under the Select column. Click Check.

6.2.3 Managing Active Jobs

As shown in Figure 6-1, the Active Jobs table on the Job Scheduler home page contains information—such as job name, class name, parameter value, job start time, and duration.

For more information on how to manage jobs, see Section 6.3, "Manage Scheduled Jobs Using the Mobile Manager".

To terminate a job, click the Administration tab, select the job, and click Delete. This does not terminate active jobs, but prevents the job from executing in the future.

6.2.4 Managing the Job History List

The number of current registered jobs in the Job History list is listed on the Job Scheduler home page under the Status Date line. Click on the number displayed to bring up the Job History page. The Job History page enables you to provide criteria to search, sort, and manage the job history based on job properties—such as name, class name, result, or a specific date and time. Based on your search criteria, the Job History page displays job history details under the Results section.

Figure 6-2 displays the Job History page.

Figure 6-2 Job History Page

Description of "Figure 6-2 Job History Page"

You can sort the messages by any of the headers. For example, to sort the job history details by name, click Name in the header title region. It toggles between A-Z and Z-A.

To delete a single job, select the job and click Delete. To delete all job history entries that match your search criteria, click Search and Delete.

6.3 Manage Scheduled Jobs Using the Mobile Manager

The most notable scheduled job is the MGP (see Section 5.1, "How Does the Synchronization Process Work?"). By default, it is scheduled to execute every 60 seconds to perform a specific task for data synchronization. You can modify the schedule of this existing job, as well as create other jobs for your own purposes to execute at a regular interval.

From the Job Scheduler screen, click the Administration tab, where you can create a new job or edit existing jobs. The Scheduled Jobs section displays the jobs that are scheduled in the job engine.

The following sections enable administrators to accomplish the following tasks:

Section 6.3.1, "Creating a New Job"
Section 6.3.2, "Editing Existing Jobs"
Section 6.3.3, "Enabling or Disabling Jobs"
Section 6.3.4, "Deleting Jobs"
Section 6.3.5, "Default Jobs"

6.3.1 Creating a New Job

In order to create a new job, you create the schedule of how often and when an existing application is executed. To create this schedule, navigate to the Job Scheduler Administration screen and click Create A New Job.

Figure 6-3 displays the top section of the Create a New Job page. Give the job a name, select the checkbox for Enabled to enable the job (or leave blank to leave disabled), and select the checkbox for Save to Job History if you want a record of this application executing.

Under the Job Class section, if this is for the MGP process, then select if this is for Apply Only or Apply and Compose. The MGP process can be modified to perform only application of new and modified records from the clients. This is beneficial for applications that never have to update information from the back-end server database. Choosing Apply Only saves performance if it is relevant for your application. For example, if you had a company that performed a lot of updates throughout the day, but no one needed to know the new information until the next day, you could schedule an MGP process to perform Apply Only all day to update the repository, and schedule another MGP process that executes only at night with Apply/Compose to perform the last updates and then bring down all of the days modifications to all of the users.

If this is not for an MGP process, then enter the class name to be executed for this job and any parameter values. Since you design the class, enter the parameter as you have designed the parameter format. There are two default jobs, which are described in Section 6.3.5, "Default Jobs".

Figure 6-3 Create a New Job - Top Section

Description of "Figure 6-3 Create a New Job - Top Section"

Figure 6-4 displays the bottom section of the Create a New Job page, which is where you define when and how often your job executes.

Figure 6-4 Create a New Job - Bottom Section

Description of "Figure 6-4 Create a New Job - Bottom Section"

Enter data in the Create a New Job page as described in the following tables.

Table 6-1 describes data that must be entered in the Start section.

Table 6-1 Start Details Description - Schedule Section

Field	Description	Required
Immediately	To start the job immediately, select this option.	Optional
Later	To start the job at a later time, select this option and specify the date and time when this job is to start.	Optional

Table 6-2 describes data that must be entered in the Expiration section.

Table 6-2 Expiration Details Description - Schedule Section

Field	Description	Required
Never Expire	To ensure that the chosen job schedule does not expire—that is, this job always executes—select this option.	Optional
Expire	If you want the job to expire after a specified number of minutes—even if it has not execute yet—then specify the number of minutes in this field. The Job Scheduler cancels jobs that do not start at the specified time. However, it does not stop jobs that have already started.	Optional

Field

Description

Required

Never Expire

To ensure that the chosen job schedule does not expire—that is, this job always executes—select this option.

Optional

Expire

If you want the job to expire after a specified number of minutes—even if it has not execute yet—then specify the number of minutes in this field.

The Job Scheduler cancels jobs that do not start at the specified time. However, it does not stop jobs that have already started.

Optional

Table 6-3 describes how often the job executes in the Repeat section.

Table 6-3 Repeat Details Description - Repeat Section

Field	Description	Required
One Time Only	The job executes only once.	Optional
Interval	The job executes after a specified interval has passed. The interval duration between execution of the job is defined in seconds.	Optional
Weekly	The job executes on the specified day of the week. You can specify an interval of whether this executes weekly (1 in the Frequency pulldown), every other week (2 in the Frequency pulldown) and so on.	Optional
Monthly	The job executes on a specified day of the month. Same as above, but with the months of the year.	Optional

Table 6-4 defines whether the chosen schedule repeats indefinitely or whether you want it to execute only on a certain date/time.

Table 6-4 Repeat Until Details Description - Repeat Section

Field	Description	Required
Indefinite	To repeat the job schedule indefinitely, select this option.	Optional
Custom	To specify how long this job executes until, specify the date and time of when the job is canceled.	Optional

To implement the job schedule after specifying changes to the schedule, click OK. To retain or restore previous job schedule values, click Cancel.

Note:

The calendar does not display the selected date if the Java script feature in your browser, any pop up blocking tools, or search tools are installed and enabled.

6.3.2 Editing Existing Jobs

Navigate to the Job Scheduler Administration screen. To edit existing jobs, click Edit. Modify the same fields that are described in Section 6.3.1, "Creating a New Job".

6.3.3 Enabling or Disabling Jobs

You can enable or disable a job from the Administration screen off of the main Job Scheduler screen. Select the job that you need to modify and either click Enable or Disable. The Status column confirms the changed status.

6.3.4 Deleting Jobs

Navigate to the Job Scheduler Administration screen. To delete a job, select the job that you need to delete and click Delete. The Job Scheduler displays a warning message that seeks your confirmation to delete the chosen job. Click Yes. You will be returned to the Administration tab.

6.3.5 Default Jobs

The Oracle Database Lite 10g Edition contains default jobs. As a user, you can enable or disable these default jobs and edit or delete them. This edition contains the following default jobs.

MGP Process: MGP_DEFAULT
Purging History: PURGE_HISTORY_DEFAULT

6.3.5.1 MGP_DEFAULT

You have to have at least a single MGP process for apply/compose phase of the synchronization phase. The MGP_DEFAULT is this process. You can modify this process to be apply only, or you can modify when the MGP process is executed. You can create other MGP processes, if you wish.

job Name

MGP_DEFAULT

Job Class

oracle.lite.sync.MgpJob

Job Parameter Value

APPLY_COMPOSE

The parameter value must be a string of the value APPLY_COMPOSE or APPLY_ONLY. When scheduling or editing this parameter using the Job Scheduler's Edit Jobs page, you can choose the required parameter value from the Apply/Compose list.

6.3.5.2 PURGE_HISTORY_DEFAULT

In order to preserve disk space, the administrator wants to purge the history. This job is created for you to automatically purge the history at a selected interval. You can modify the interval or disable this job, if you wish. This section describes the job class, job parameter value and its corresponding description.

Job Name

PUR GE_HISTORY_DEFAULT

Job Class

oracle.lite.sync.PurgeHistoryJob

Job Parameter Value

History=Sync,MGP,Job;Days=7

Since this Job is a customized class, the parameter is defined and parsed within the purge history class. The structure of this parameter is a string with two name/value pairs: what type of history to purge and for how many days. In this example, the history purged is for the Sync, MGP, and Job historical data. The history is purged for the last seven days. You can modify the number of days or add/delete the history logs that this applies to. The only options are Sync, MGP, or Job. For example, if you want every record that is 3 days old or more to be erased, modify the 7 to a 3.

6.4 Managing Scheduled Jobs Using ConsolidatorManager APIs

Application developers can define, submit, and manage jobs programmatically based on a pre-determined time and interval. For example, jobs can be scheduled to run repeatedly for a specified duration on any specified day or days of the week or month. Administrators can schedule jobs to run repeatedly for a specified number of months, weeks or specified days of the month or week.

The Job Scheduler provides an API for scheduling and running jobs using a job engine. It is a generic component which enables apply and compose functions for MGP, device manager jobs, and custom jobs.

Using the class oracle.lite.sync.ConsolidatorManager, application developers can register or de-register a job class, create, drop, enable or disable a job, search, and delete a job execution log.
Use other supporting classes, such as Job, Schedule, ExecutionResult and ExecutionLog in the oracle.lite.sync.job package to manage your scheduled jobs.

For more information on these classes and their methods, refer to the Oracle Database Lite API JavaDoc.

6.4.1 Start Job Scheduler In Separate JVM

If you want to execute the Job Scheduler in a different JVM from the Mobile Server, then perform the following:

Retrieve a connection to the database with the Consolidator Manager openConnection method. Pass in the Mobile Manager administrator username, password and optionally, the JDBC URL to the back-end Oracle database.
Create a new Job engine with the JobEngine class and start it with the startUp method. The Job engine executes in a separate thread, which you can terminate from the main thread.
Define how long the thread is to sleep between execution of all jobs.
Terminate the Job engine when you have completed all activities.

Note:

The following example demonstrates how to start up the Job engine in another thread from the Mobile Server. It executes all of the jobs that have been scheduled either through the API or through the Mobile Manager Job Scheduler screens, because the Job Scheduler retrieves the scheduled job information from the repository.

JobEngine JobEngine = new JobEngine();
JobEngine.startUp();
if (JobEngine.runnerThreadException != null){
  System.out.println("runnerThreadException:");
  JobEngine.runnerThreadException.printStackTrace();
}
 
Thread.currentThread().sleep(60*1000);
 
if (JobEngine.runnerThreadException != null){
  System.out.println("runnerThreadException:");
  JobEngine.runnerThreadException.printStackTrace();
}
JobEngine.shutDown();

6.5 Using the ConsolidatorManager APIs to Create Jobs

Within the oracle.lite.sync.ConsolidatorManager class, there are several APIs, which are documented fully in the Oracle Database Lite API JavaDoc, that enable you to create, register, and schedule your job.

While these methods are described fully in the JavaDoc, the following demonstrates the order in which you would execute the methods:

Create your job class by implementing the oracle.lite.job.Job interface. Implement the Job interface methods, as follows:
- init method—This method is invoked by the Job Scheduler when the job is loaded.
- execute method—This method is invoked by the Job Scheduler when the job is scheduled to execute. Put a call into your application within this method. The Job Scheduler passes in the input parameter that was provided when the job is created—either with the createJob method or within the Mobile Manager Job Scheduler screen. When finished, the execute method returns an object of class type ExecutionResult containing whether the job was a success or failure.
- destroy method—This method is invoked after the job completes.
After you have created your job class, register it with the registerJobClass method.
Create the job in the Job Scheduler by executing the createJob method. One of the input parameters is an object of class type Schedule, which defines when the job is executed. There are also other management methods that correspond to the Mobile Manager GUI, such as dropJob, enableJob, and disableJob.
If you want to retrieve any logs, execute the getJobExecutionLogs method, which retrieves objects of ExecutionLog class.