Workspace Resource Programming

In Chapter 23, Workspace Resource Programming, you learned about the structure of the resource model and how it can help your plug-in to create and manage resources as well as dynamically react to changes. The key to resource programming is understanding how to issue the API calls based on what you need to do; this includes the use of runnable units of code and the abstract class WorkspaceJob to consolidate event notifications and improve workspace concurrency.

The com.ibm.jdg2e.resources.programming project demonstrates the various techniques for how resources can be accessed and created. This is done using several examples of performing the same set of operations using different approaches.

Running the Example

There are a series of examples included in this project. Each demonstrates what can be done using a portion of the resources API.

To begin, launch a runtime workbench (Run > Run As > Eclipse Application).

Access Resource Information

You can use the resource API to access information about a resource.

In the Navigator view, select the JDG2E: List Project Locations action from the view pulldown menu. It accesses the workspace and retrieves all projects, then displays a dialog with the file system location for each project (see ProcessResourceTree).

Select any resource in the Navigator view and use the JDG2E: Resource Demos > List Path Values pop-up menu action (see ProcessResourceTree).

JDG2E: Resource Demos > List Path Values

Control Visibility and Display of Resources

You can alter what resources are visible in the Navigator view or change how their labels are rendered.

Select the Filters... option in the Navigator view drop-down menu. This chapter's plug-in adds two filters for .cvsignore and temp.folder by contributing to the org.eclipse.ui.ide.resourceFilters extension point.

Open the Window > Preferences dialog and turn to the Workbench > Label Decorators page.

If the JDG2E: CVS Ignore Decorator is selected and you have one or more .cvsignore files present, the resources being ignored will be identified using brackets.

Create Resources While Managing the Resource Change Events

Resource creation is straightforward, but the more important task is managing the number of resource change events that are triggered and allowing concurrent access to the workspace when possible.

Open the JDG2E: > Resource Change Events view.

This view has been provided to help you see when resource change events are triggered, and even get a count of them for a given operation. You can also copy/paste the list content to a text file if you need to save the data for further study. When you open the view resource change listening is off. Use the toolbar toggle () to add/remove the resource change listener. The event detail for the creation of a simple project is shown.

A set of actions are available in the Navigator view pop-up menu when a project is selected. These actions all do the same thing: Add a set of folders and files to a project when they do not already exist. One file is copied from the plug-in's installation directory, the other is created with content from the code. What differs for each action is how it is implemented and what it means in terms of resource change events and concurrent access to the workspace.
JDG2E: Resource Demo

Action Description

Setup Project Structure Nothing special, just standard resource creation; no event management.

Setup Project Structure
using Runnable An IWorkspaceRunnable is used to manage events.

Setup Project Structure
using Runnable with Project Rule An IWorkspaceRunnable is used to manage events; in addition the selected project is used as an ISchedulingRule to allow the operation to run concurrently with other resource actions.

Setup Project Structure
using Visible Progress Monitor Shows progress of task. There are delays built in so that the progress is visible.

Setup Project Structure
using Job The resources are created in a job, this is similar to the first option with respect to events, but the UI is freed up once the job is scheduled. Delays are built in so the processing is visible. Try to start this operation on two different projects at the same time. The events will be interleaved.

Setup Project Structure
using Job with Project Rule The resources are created in a job. This is similar to the previous option, but the scheduling rule will potentially allow the operation to run concurrently with other active processing on other threads.

Setup Project Structure
using WorkspaceJob The resources are created in a WorkspaceJob. This runs the work in a job but is more like an IWorkspaceRunnable in that events are batched. They are not limited quite as much as with the second option, but there are fewer events than many of the other techniques. Try and delete a folder after it is created, but before the job ends.

Roadmap of the Example

The Resource Programming plug-in is designed to help you understand not only the basics of interacting with the workspace, but the implications of different strategies for resource modification and event management.

The plug-in manifest file defines the extension definitions for the different actions, resource filters, label decorator, and the view that tracks resource change events. The key classes from the com.ibm.jdg2e.resources.programming package that are used to implement the examples are shown in the table below.

Class (All)	Description
`ProcessResourceTree`	This class implements both the JDG2E: List Project Locations and JDG2E: Resource Demos > List Path Values actions.
`CVSIgnoredResourceDecorator`	Implements the label decorator that identifies resources ignored by CVS.
`ResourceChangeReporter`	Resource change listener that tracks events. The delta is processed by `ResourceDeltaPrinter`.
`RCLView`	View that displays the tracked events. The `TraceToListJob` subclass of `WorkbenchJob` is used with a custom scheduling rule implementation, `SequenceRule`, to ensure the events are written to the view in sequence without using a `Display.syncExec`.
`StructureProjectAction`	This class implements all of the Setup Project Structure ... actions.

Action	Description
Setup Project Structure	Nothing special, just standard resource creation; no event management.
Setup Project Structure using Runnable	An `IWorkspaceRunnable` is used to manage events.
Setup Project Structure using Runnable with Project Rule	An `IWorkspaceRunnable` is used to manage events; in addition the selected project is used as an `ISchedulingRule` to allow the operation to run concurrently with other resource actions.
Setup Project Structure using Visible Progress Monitor	Shows progress of task. There are delays built in so that the progress is visible.
Setup Project Structure using Job	The resources are created in a job, this is similar to the first option with respect to events, but the UI is freed up once the job is scheduled. Delays are built in so the processing is visible. Try to start this operation on two different projects at the same time. The events will be interleaved.
Setup Project Structure using Job with Project Rule	The resources are created in a job. This is similar to the previous option, but the scheduling rule will potentially allow the operation to run concurrently with other active processing on other threads.
Setup Project Structure using WorkspaceJob	The resources are created in a `WorkspaceJob`. This runs the work in a job but is more like an `IWorkspaceRunnable` in that events are batched. They are not limited quite as much as with the second option, but there are fewer events than many of the other techniques. Try and delete a folder after it is created, but before the job ends.