12 Defining and Using a Job Incompatibility

This chapter describes how to use an Oracle Enterprise Scheduler job incompatibility. The incompatibility feature lets you specify job requests that cannot run together.

This chapter includes the following sections:

Section 12.1, "Introduction to Using a Job Incompatibility"
Section 12.2, "Defining Incompatibility with Oracle JDeveloper"
Section 12.3, "What Happens at Runtime to Handle Job Incompatibility"

For information about how to create and submit job requests see the following chapters, for Java jobs, Chapter 3, "Use Case Oracle Enterprise Scheduler Sample Application", and Chapter 6, "Creating and Using PL/SQL Jobs", and Chapter 7, "Creating and Using Process Jobs". For more information on using job sets, see Chapter 11, "Defining and Using Job Sets".

Note:

To simplify the discussion we refer only to job definitions in this incompatibility chapter, but in all cases this discussion applies to both job definitions and job sets.

12.1 Introduction to Using a Job Incompatibility

A given incompatibility specifies either a global incompatibility or a domain, property-based, incompatibility. Oracle Enterprise Scheduler supports incompatibility between job definitions or job sets based on an incompatibility definition as represented by the oracle.as.scheduler.Incompatibility Java class. The IncompatibilityType enum specifies the valid incompatibility types.

Domain-Specific (DOMAIN): where at most two job definitions are marked as incompatible within the scope of a resource, where the resource is identified by a system property name or a user-defined parameter name. A property name must be specified for each job definition used to define the incompatibility. Parameters specified through parameterVO will be submitted to the request as request properties submit.argument1, ... submit.argument#. In the incompatibility definition for the properties, specify submit.argument1, ... submit.argument#, Oracle Enterprise Scheduler ensures that requests for the incompatible jobs do not run at the same time if they have the same value for that resource.
Global (GLOBAL): where at most two job definitions are marked as incompatible, regardless of any resource or property. Oracle Enterprise Scheduler ensures that requests for the incompatible jobs do not run at the same time.

An Oracle Enterprise Scheduler incompatibility definition specifies either a global incompatibility or a domain (property-based) incompatibility. An incompatibility consists of at most two entities (job definition or job set) and the resource over which they need to be incompatible. A resource is not specified for a global incompatibility. Each entity can be flagged as being self-incompatible. Oracle Enterprise Scheduler does not support a mixed mode where one entity represents a domain (property-based) entity and another entity represents a global (no property) entity.

For a domain incompatibility, the resource is represented by a property name that might be different for each entity of the incompatibility. For example, if a domain incompatibility is created for two job definitions, JobA and JobB, then the resource (property) identified for each entity might have different property names in JobA and JobB. It might be called foo in JobA while it might be called foo2 in JobB. Oracle Enterprise Scheduler considers a request for JobA and a request for JobB to be incompatible if they have the same value for their respective property, and those requests would not run at the same time. If the requests have a different value for their respective property, they are considered compatible and allowed to run concurrently.

An incompatibility definition specifies which job definition is incompatible with another job definition. A given job definition does not directly point to or reference any incompatibility definitions.

Oracle Enterprise Scheduler determines which, if any, incompatibility definitions reference the job definition at request submission. It also determines the resource (property) value for any domain incompatibility. That information is used throughout the processing life cycle of the request.

12.1.1 Job Self Incompatibility

A job definition or job set can be defined as self incompatible where the job definition or job set is incompatible with itself. A self-incompatibility implies that multiple job requests associated with a single job definition cannot run together. An incompatibility definition can contain a single entity if it is marked as self-incompatible. For global self-incompatibly, Oracle Enterprise Scheduler ensures that multiple requests for that particular job or job set definition are not run simultaneously. For property-based self-incompatibly, Oracle Enterprise Scheduler ensures that requests for that particular job or job set definition, and having the same value for the property, are not run at the same time.

12.2 Defining Incompatibility with Oracle JDeveloper

You can define an incompatibility in Oracle JDeveloper by specifying the following:

The name and package for the incompatibility
The incompatibility type
The entity for the incompatibility and whether there is a self incompatibility
For a domain specific incompatibility, the property associated with the incompatibility for each entity

12.2.1 How to Define a Global Incompatibility

An Oracle Enterprise Scheduler global incompatibility is defined by a name, a package and entities.

To create a global incompatibility:

In Oracle JDeveloper, right-click in the project to view the New Gallery.
Under Categories, expand Business Tier and select Enterprise Scheduler Metadata.
Under Items, select Incompatibility and click OK. This displays the Create Incompatibility window, as shown in Figure 12-1.

Figure 12-1 Create Incompatibility Window
Use the Create Incompatibility dialog to specify the following:
1. In the Name field, enter a name for the incompatibility or accept the default name.
2. In the Package field, enter a package name for the incompatibility.
3. The Location field displays the full path of the directory where the incompatibility file is stored.
4. In the Incompatibility Type field, select Global. and click OK.
  
  The incompatibility is created, and the Incompatibility Definition page displays.
In the Incompatibility Editor pane, in the Description field enter a description for the incompatibility.
In the Incompatibility Entities area, click Add to add entities. This displays the Add Entity dialog, as shown in Figure 12-2.

Figure 12-2 Incompatibility Add Entity Window
Select one or more entities for the incompatibility and click OK. The Incompatibility Editor displays.
To specify a self incompatibility or to change the entity, double-click the entity in the Entities area. This displays the Edit Entity dialog as shown in Figure 12-3.

Figure 12-3 Edit Entity Window for Global Incompatibility
To specify self incompatibility, select Self Incompatible.
Save the incompatibility.

12.2.2 How to Define a Domain Incompatibility

An Oracle Enterprise Scheduler domain incompatibility is defined by a name, a package, entities, and properties for each entity.

To create an incompatibility:

In Oracle JDeveloper, right-click in the project to view the New Gallery.
Under Categories, expand Business Tier and select Enterprise Scheduler Metadata.
Under Items, select Incompatibility and click OK. This displays the Create Incompatibility window.
Use the Create Incompatibility dialog to specify the following:
1. In the Name field, enter a name for the incompatibility or accept the default name.
2. In the Package field, optionally enter a package name for the incompatibility.
3. The Location field displays the full path of the directory where the incompatibility file is stored.
4. In the Incompatibility Type field, select Domain, as shown in Figure 12-4.
  
  Figure 12-4 Create Incompatibility Window
  
  Click OK. This creates the incompatibility and displays the Incompatibility Editor.
In the Incompatibility Editor pane, in the Description field enter a description for the incompatibility.
In the Incompatibility Entities area, click Add.

The Add Entity window displays.
Select one or more jobs or job sets to add to the incompatibility and click OK.

The Incompatibility Editor displays.
To specify a self incompatibility or modify an entity or its properties, under the Entities field, double-click an entity.

The Edit Entity window displays, as shown in Figure 12-5.

Figure 12-5 Incompatibility Edit Entity Window
To specify self incompatibility, select Self Incompatible.
Save the incompatibility.

12.3 What Happens at Runtime to Handle Job Incompatibility

At runtime, Oracle Enterprise Scheduler handles incompatibility definitions according to the incompatibility type, global or domain (property-based). When a job request is submitted, Oracle Enterprise Scheduler determines which incompatibility definitions reference the job or job set definition used for the request submission. For each domain incompatibility it also determines the value of the resource, property, for that incompatibility. When the request is ready to be executed, Oracle Enterprise Scheduler checks if there are any incompatible requests already executing. If so, the request is blocked until all requests for which it is incompatible have completed.

Note:

The value of the property for a domain incompatibility is determined at request submission, and originates either in the job definition or a request parameter passed during submission. If no such parameter is found, that incompatibility is ignored during subsequent request processing. The request will be compatible with any other request with regard to that incompatibility definition. This initial value as specified at request submission time is used even if it is subsequently altered.

12.3.1 What Happens to Subrequests with an Incompatible Parent Request

A request which is incompatible with another request is also incompatible with the subrequests of that request (the children). A request that has been blocked by a subrequest parent remains blocked while any subrequests execute and until the subrequest parent request is resumed and completes.

12.3.2 What Happens to the Scope of Request Incompatibility

Every validated request is assigned to an enterprise. Incompatibility is supported only among requests that are associated with the same enterprise. A request for one enterprise is never incompatible with a request for a different enterprise even if an incompatibility has been defined between the job definitions used by those requests.