Implementing Responsiveness and Concurrency Using Jobs

In Chapter 29, Implementing Responsiveness and Concurrency Using Jobs, you learned how to use jobs to implement asynchronous processing as part of your plug-in. You also learned about the different types of jobs, the processing options, and techniques for interacting with the user. The com.ibm.jdg2e.concurrency project demonstrates the basics of the Jobs API. This project and the testing script that follows in the next section should give you a good introduction to what can be done using the Jobs API.

Practical examples of the use of jobs and scheduling rules can be found in the views provided as part of the File Resources View plug-in, defined in the com.ibm.jdg2e.view.files project and Resource Programming plug-in, defined in the com.ibm.jdg2e.resources.programming project.

Running the Example

Launch and run a runtime workbench (Run > Run As > Eclipse Application).
Open the JDG2E: Jobs Demonstration perspective.
)
Explore the different API demonstrations, they are organized by tab as described in the following sections.

Control Buttons

Run Specified Job Creates and schedules job with the selected attributes.

Reschedule Last Job Send previously scheduled job another schedule request.

Cancel Last Job Send cancel request to active job; disabled if no active job.

Wake Sleeping Job Send wake request to a sleeping job.

Clear List Empty list of displayed job change listener events.

Job Basics Tab

Add Job Listener Uses a Job Change Listener to identify events and write details to list in UI.

Run as UIJob Wrap requested processing in CustomUIJob, a form of UIJob.

Wait on Job Completion Uses a join request on the scheduled job to wait for job completion. Demonstrates that waiting is not always recommended (locks the UI).

Self Repeating Job Tells the scheduled job to schedule itself when done, this reschedule request will be honored until the job is canceled using the Progress view. Reschedule delay is based on identified Job Priority.

Job Result Tells job what status to return at completion. Can impact the result of job processing and user interface interaction. An Info status triggers custom logic that forces the job to stay in the Progress view.

Add Post-Job Action Uses the IProgressConstants.ACTION_PROPERTY to associate an action to the job that will be available for launch in the UI. Only works if the job is kept in the Progress view after completion. Custom logic forces an Info status job to stay around. The Keep Jobs in View option on the User Interaction tab can also be used to keep a job around and make the associated action visible.

Start Delay Schedules the job with a delay. A delay is required if you want to sleep the job as well.

Sleep Issues a sleep request for a job just after it has been scheduled with a delay. The Wake Sleeping Job button must be used to get the job running again.

Job Priority Determines what priority to assign to the job. The priority value is also reused to determine the delay for a Self Repeating Job.

User Interaction Tab

Run as System Job Identifies the job as a system job which prevents it from being displayed by default in the Progress view.

Fail Job Forces the job to throw an exception; triggers an error dialog.

Run Using Dialog Uses the IWorkbenchSiteProgressService.showInDialog API to force the job to run in a dialog. This dialog can be dismissed by the user with a Run in Background request. The dialog will not be shown if the Always run in background Workbench preference has been selected.

Use Custom Job Image Associates an image with all jobs in the same family. Each job must respond true to the belongsTo request in order for the job image to be displayed when it is active in the Progress view.

User Initiated Job Sets the job up as a user job which triggers the use of a dialog to run the job. Same result as the Run Using Dialog option but simpler API (setUser(true))

Schedule w/PartService API Workbench parts can use an API to schedule a job, This can be used to tell the workbench that the part has an active job which triggers visual clues. The title bar and a half busy cursor are requested for this call. Cursor is only busy when above the part (view) that scheduled the job.

Keep Jobs in View dropdown Identifies if none (default), one, or all jobs should be kept in the Progress view once complete. This is required for the Add Post-Job Action request that can be made on the Job Basics tab.

Choose Shared Progress Monitor Jobs can be run under a shared monitor. If one is selected it will be used, Each monitor is defined such that it takes five jobs for the monitor to reach 100% completion.

Managing Job Contention Tab

Choose Scheduling Rule - Two Rule Families: IResource and Blood Type

No Rule Jobs are run without a scheduling rule.

Workspace Root Rule Any IResource can be a scheduling rule. This uses the workspace root itself. Two jobs with the same IResource based rule cannot run at the same time.

Selected Resource Rule Select a resource in the Navigator view and it will be used as the scheduling rule. Two jobs with the same IResource based rule, or have a rule that includes, or is included by another rule, cannot run at the same time. Start one job with a project and another job with a folder or file in that project.

Limited Use of Rule Identifies that the job should use beginRule/endRule logic within job processing. The workspace root is the rule used; this makes a rule act a bit like a lock.

Type Rule When running, any other type rule can run at the same time.

Type AB Rule When running, any other type specific rule can run at the same time (universal receiver).

Type A Rule When running, any other type specific rule, except Type B, can run at the same time.

Type B Rule When running, any other type specific rule, except Type A, can run at the same time.

Type O Rule When running, no other type rule can run at the same time (universal donor).

Note: Yes, the blood type rule is odd, but it demonstrates that complex scheduling rules can be defined.

Choose Lock

No Lock No lock is used during job processing.

Lock A A common lock named "A" is acquired after the job starts and released half way through job processing logic.

Lock B A common lock named "B" is acquired after the job starts and released half way through job processing logic.

Roadmap of the Example

The Concurrency/Jobs API Demonstration plug-in helps you understand the dynamics of using jobs in Eclipse and provide small examples of how the API can be used. To do this, a Jobs Demo view has been provided, along with a JDG2E: Jobs Demonstration perspective to organize the different views needed during a full demonstration.

The view has a user interface, actions in the toolbar and pull-down menu, as well as the context menu for the viewer used in the user interface. This is the limit of its function.

The plug-in manifest file defines the extension definition for the Jobs Demo view and perspective to organize the demonstration. This description can also be opened by pressing F1 in the Jobs Demo view.

These are the key classes from the com.ibm.jdg2e.concurrency package that are used to implement the job processing demonstration.

Class (All)	Description
`JobsView`	This class implements the view's user interface and function. This includes many of the API calls required to setup and customize job processing.
`JobDemoPerspective`	Implements the custom perspective for this demo.
`CustomJob`	Used to display content for the `ILocation` view.
`CustomJob`	Extended implementation of a `Job`, this code provides the customized processing that demonstrates the API.
`CustomUIJob`	Extended implementation of a `UIJob`, this code provides the customized processing that demonstrates the API.
`CustomJobListener`	An `IJobChangeListener` implementation that is used to track job activity to the list in the Jobs Demo view.
`CustomJobWork`	Implements demo processing for jobs, this is just a loop that sleeps long enough to make the job visible in the Progress view.
`Custom Scheduling Rules`	Implementation of a set of rules that govern when job can run. The problem being solved is blood mixing rules. A scheduling rule that forces sequential execution of a `WorkbenchJob` can be found in the Resource Programming plug-in project, `com.ibm.jdg2e.resources.programming`.

Run Specified Job	Creates and schedules job with the selected attributes.
Reschedule Last Job	Send previously scheduled job another schedule request.
Cancel Last Job	Send cancel request to active job; disabled if no active job.
Wake Sleeping Job	Send wake request to a sleeping job.
Clear List	Empty list of displayed job change listener events.

Add Job Listener	Uses a Job Change Listener to identify events and write details to list in UI.
Run as `UIJob`	Wrap requested processing in `CustomUIJob`, a form of `UIJob`.
Wait on Job Completion	Uses a join request on the scheduled job to wait for job completion. Demonstrates that waiting is not always recommended (locks the UI).
Self Repeating Job	Tells the scheduled job to schedule itself when done, this reschedule request will be honored until the job is canceled using the Progress view. Reschedule delay is based on identified Job Priority.
Job Result	Tells job what status to return at completion. Can impact the result of job processing and user interface interaction. An Info status triggers custom logic that forces the job to stay in the Progress view.
Add Post-Job Action	Uses the `IProgressConstants.ACTION_PROPERTY` to associate an action to the job that will be available for launch in the UI. Only works if the job is kept in the Progress view after completion. Custom logic forces an Info status job to stay around. The Keep Jobs in View option on the User Interaction tab can also be used to keep a job around and make the associated action visible.
Start Delay	Schedules the job with a delay. A delay is required if you want to sleep the job as well.
Sleep	Issues a sleep request for a job just after it has been scheduled with a delay. The Wake Sleeping Job button must be used to get the job running again.
Job Priority	Determines what priority to assign to the job. The priority value is also reused to determine the delay for a Self Repeating Job.

Run as System Job	Identifies the job as a system job which prevents it from being displayed by default in the Progress view.
Fail Job	Forces the job to throw an exception; triggers an error dialog.
Run Using Dialog	Uses the `IWorkbenchSiteProgressService.showInDialog` API to force the job to run in a dialog. This dialog can be dismissed by the user with a Run in Background request. The dialog will not be shown if the Always run in background Workbench preference has been selected.
Use Custom Job Image	Associates an image with all jobs in the same family. Each job must respond true to the `belongsTo` request in order for the job image to be displayed when it is active in the Progress view.
User Initiated Job	Sets the job up as a user job which triggers the use of a dialog to run the job. Same result as the Run Using Dialog option but simpler API (`setUser(true)`)
Schedule w/PartService API	Workbench parts can use an API to schedule a job, This can be used to tell the workbench that the part has an active job which triggers visual clues. The title bar and a half busy cursor are requested for this call. Cursor is only busy when above the part (view) that scheduled the job.
Keep Jobs in View dropdown	Identifies if none (default), one, or all jobs should be kept in the Progress view once complete. This is required for the Add Post-Job Action request that can be made on the Job Basics tab.
Choose Shared Progress Monitor	Jobs can be run under a shared monitor. If one is selected it will be used, Each monitor is defined such that it takes five jobs for the monitor to reach 100% completion.

No Rule	Jobs are run without a scheduling rule.
Workspace Root Rule	Any `IResource` can be a scheduling rule. This uses the workspace root itself. Two jobs with the same `IResource` based rule cannot run at the same time.
Selected Resource Rule	Select a resource in the Navigator view and it will be used as the scheduling rule. Two jobs with the same `IResource` based rule, or have a rule that includes, or is included by another rule, cannot run at the same time. Start one job with a project and another job with a folder or file in that project.
Limited Use of Rule	Identifies that the job should use `beginRule/endRule` logic within job processing. The workspace root is the rule used; this makes a rule act a bit like a lock.
Type Rule	When running, any other type rule can run at the same time.
Type AB Rule	When running, any other type specific rule can run at the same time (universal receiver).
Type A Rule	When running, any other type specific rule, except Type B, can run at the same time.
Type B Rule	When running, any other type specific rule, except Type A, can run at the same time.
Type O Rule	When running, no other type rule can run at the same time (universal donor).

No Lock	No lock is used during job processing.
Lock A	A common lock named "A" is acquired after the job starts and released half way through job processing logic.
Lock B	A common lock named "B" is acquired after the job starts and released half way through job processing logic.