18 Defining and Using a Job Incompatibility

This chapter describes how to use an Oracle Enterprise Scheduler job incompatibility, with which you can specify job requests that cannot run together.

This chapter includes the following sections:

• Introduction to Using a Job Incompatibility

• Defining Incompatibility with Oracle JDeveloper

• What Happens at Runtime to Handle Job Incompatibility

For information about how to create and submit job requests see Creating and Using PL/SQL Jobs , and Creating and Using Process Jobs . For more information on using job sets, see 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.

18.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 one or more 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. 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. Parameters specified through parameterVO are submitted as request properties having the property name submit.argument1, ... submit.argument#. To use such a parameter as the domain incompatibility property, specify submit.argument1, ... submit.argument# for the incompatibility property name.

• Global (GLOBAL): where one or more 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 one or more entities (job definition or job set) and the resource over which they must be incompatible. A resource is not specified for a global incompatibility. Each entity can be flagged as being self-incompatible. If an incompatibility is defined for only one entity that entity must be flagged as 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 of a request when it is about to executed for the first time. It also determines the resource (property) value for any domain incompatibility at that time. That information is used throughout the subsequent processing life cycle of the request, including any retries of the request. For job set requests, Oracle Enterprise Scheduler determines which, if any, incompatibility definitions reference the job definition of any potential job set step when the top-most job set request is about to be executed rather than when individual step requests are executed.

For a Schedule-based submission, Oracle Enterprise Scheduler creates new child requests for instances of the Schedule. Only one instance request is executed at a given time. Oracle Enterprise Scheduler tracks metadata changes made to incompatibility definitions and may refresh the incompatibility definitions, if any, when an instance request is about to be executed for the first time. This means the incompatibility definitions used when the next instance request is executed may be different than the incompatibility definitions used when a prior instance request was executed.

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

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

18.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:

1. In Oracle JDeveloper, right-click in the project to view the New Gallery.

2. Under Categories, expand Business Tier and select Enterprise Scheduler Metadata.

3. Under Items, select Incompatibility and click OK. This displays the Create Incompatibility window, as shown in Figure 18-1.

   Figure 18-1 Create Incompatibility Window

   
   Description of "Figure 18-1 Create Incompatibility Window"

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

5. In the Incompatibility Editor pane, in the Description field enter a description for the incompatibility.

6. In the Entities area, click Add to add entities. This displays the Add Entity dialog, as shown in Figure 18-2.

   Figure 18-2 Incompatibility Add Entity Window

   
   Description of "Figure 18-2 Incompatibility Add Entity Window"

7. Select one or more entities for the incompatibility and click OK. The Incompatibility Editor displays.

8. 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 18-3.

   Figure 18-3 Edit Entity Window for Global Incompatibility

   
   Description of "Figure 18-3 Edit Entity Window for Global Incompatibility"

9. To specify self incompatibility, select Self Incompatible.

10. Save the incompatibility.

18.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:

1. In Oracle JDeveloper, right-click in the project to view the New Gallery.

2. Under Categories, expand Business Tier and select Enterprise Scheduler Metadata.

3. Under Items, select Incompatibility and click OK. This displays the Create Incompatibility window.

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

      Figure 18-4 Create Incompatibility Window

      
      Description of "Figure 18-4 Create Incompatibility Window"

      Click OK. This creates the incompatibility and displays the Incompatibility Editor.

5. In the Incompatibility Editor pane, in the Description field enter a description for the incompatibility.

6. In the Incompatibility Entities area, click Add.

   The Add Entity window displays.

7. Select one or more jobs or job sets to add to the incompatibility and click OK.

   The Incompatibility Editor displays.

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

   Figure 18-5 Incompatibility Edit Entity Window

   
   Description of "Figure 18-5 Incompatibility Edit Entity Window"

9. To specify self incompatibility, select Self Incompatible.

10. Save the incompatibility.

18.3 What Happens at Runtime to Handle Job Incompatibility

Oracle Enterprise Scheduler handles incompatibility definitions according to the incompatibility type, global or domain (property-based), at runtime.

When a job request is about to be executed, 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 or property, to use for that incompatibility. Oracle Enterprise Scheduler checks to determine if there are any incompatible requests already executing. If so, the request is blocked until all requests with which it is incompatible have completed.

Note:

The value of the property for a domain incompatibility is obtained from the request parameters at request execution. That value usually originates either in the job definition or in a request parameter specified at request submission. If no such parameter is found, that incompatibility is ignored during subsequent request processing. The request is compatible with any other request with regard to that incompatibility definition. This initial property value is used as the incompatibility resource value even if the property is subsequently altered.

18.3.1 What Happens to Subrequests with an Incompatible Parent Request

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