Managing Resources with Natures and Builders / Resource Tagging Using Markers

In Chapter 24, Managing Resources with Natures and Builders and Chapter 25, Resource Tagging Using Markers, you learned how to extend the capability of the workspace by defining extensions. These workspace extensions add behaviors to projects (natures and builders) and define new types of markers than can tag resources with additional information. The com.ibm.jdg2e.resources.extensions project demonstrates the resource extensions, and how they can be used to enhance the capabilities of a project and other workspace resources.

Running the Example

This project includes a series of examples. Each demonstrates what can be done using one or more of the resource extension types. This typically involves the use of the resource programming API. See the Resource Programming plug-in, defined in project com.ibm.jdg2e.resources.programming for additional examples.

To begin, launch a runtime workbench (Run > Run As > Eclipse Application). From here we'll follow a natural exploration of the function provided in this plug-in.

Marker Extensions

New marker types can be defined to record information about a resource. For example, a marker might be used to denote a resource's location like a bookmark, or add information related to the resource, like a task to be completed. The example's plug-in manifest file defines a marker extension with an id of com.ibm.jdg2e.resources.extensions.recentEdits. This marker is used to tag files that have been recently edited (modified).

Modified files are identified using a resource change listener. To provide this support from the moment Eclipse is launched, this plug-in contributes to the org.eclipse.ui.startup extension point. This requests that the Workbench activate the plug-in and call its implementor of IEarlyStartup once the main window opens; this also activates the plug-in. In the plug-in's start method the resource change listener is added to the workspace.
You can tell the plug-in starts early if you review the Workbench > Startup and Shutdown preference page. The JDG2E: Resource Extensions plug-in is listed.
The use of recent edit markers is customizable. The number of markers kept (files identified) can be set and the change tracking disabled using a preference page.
Review the JDG2E: Recent Edits preferences page; adjust any control options you want, but keep Track Recent File Edits checked for the moment.
When enabled, this plug-in's resource change listener will note when you have modified a file by adding a "recent edits" marker to that file. Try it by modifying an existing file, or creating a new file and then modifying it. As the marker is defined with supertypes of org.eclipse.core.resources.taskmarker, org.eclipse.core.resources.bookmark, and org.eclipse.core.resources.textmarker, the new marker will show up in both the Tasks and Bookmarks views and can interact with text editors. If the recent edit markers are not visible you may need to adjust the view filters to include the recent edits marker type.

Note: The Marker View plug-in, defined in the com.ibm.jdg2e.view.marker project, includes a view that is designed to find and display only recent edit markers.
You can disable modification markers or limit the number of markers kept using the preference settings. If you want the recent edits process to ignore only certain files you can adjust the properties for those files. Open the Properties dialog for the file and select Exclude from Recent Editor Marker Support on the JDG2E: Resource Extensions property page.

If you modify a file after selecting the exclude option, a marker will not be created.
And just in case you want to remove all these markers, the plug-in also contributes an action using the org.eclipse.ui.popupMenus extension point. The action targets all markers whose message property (Description column) starts with "aRE". This action shows up for recent edit markers regardless of the view in which they are shown; the pop-up menu action can be found in the Tasks and Problem views from Eclipse as well as the Recent Edit Markers view provided as part of the com.ibm.jdg2e.view.marker project.
The JDG2E: Delete All Recent Edit Markers action is available from the pop-up menu of any selected recent edit marker.

Quick fix support and contextual help can be defined for a marker. In addition, markers are often related to builder processing. These capabilities and relationships will be covered in the next section.

Natures and Builders

To create a nature or builder, you first define them as extensions in your plug-in, provide an implementation for these extensions, and then either create a project that includes the nature or add the nature to an existing project. Builders can be used without a nature, but the expected usage pattern in Eclipse is to have a nature that customizes a project by adding any builders that are required.

The example's plug-in manifest file defines extensions for a nature, nature image, and builder. When added to a project, the nature will decorate the project with a nature image if it is the first nature known to the project that has an image. The provided implementation for the nature is limited to adding the readme builder. The readme builder will process .readme files found in a readme folder and create an .html file with the content of the readme wrapped by some HTML markup.

The readme builder also tracks deletions to .readme files. The builder does not delete the matching .html file, but instead creates a marker to identify the orphan. The marker includes help to tell you what to do and a suggested Quick Fix to correct the problem.

Create a new project using the JDG2E > New Project (with CustomNature) wizard.

This will add a new project to the workspace. The CustomNature and its associated image () will be associated with the project. The nature will add the builder. This is recorded in the .project file for the project.

Add a readme folder and a .readme file (such as abc.readme) to the proejct. If you have the com.ibm.jdg2e.resources.programming project loaded, you can use one of the Setup Project Structure actions to create the folder and file.

Once the .readme file has been created the builder will be invoked (unless you turned off the automatic build process). If the .html file is not created, verify the Project > Build automatically menu choice is checked.

Delete the .readme file leaving an orphan .html file. The builder notices this and complains by adding a problem marker to the .html file. This marker should be visible in the Problems view. Help has been defined for this marker; select it in the Problems view and press F1.
To resolve this problem we have defined a marker resolution extension. Select the marker and choose the Quick Fix option in the pop-up menu.

When you choose the fix you are prompted to either delete the .html file or change it so it is not marked as derived (a resource API call).

Note: There are some additional actions included in the plug-in located in the pop-up menu for a project (JDG2E: Resource Demos > ...). These actions are available only in the Navigator view and can be used to directly add a nature to a project, list builders for a project, and even add or remove the readme builder. The nature and builder have a defined relationship via the of the org.eclipse.core.resources.natures and org.eclipse.core.resources.builders extensions, so if you want to directly add the builder you will have to modify the extension definitions to remove this relationship.

Roadmap of the Example

The Resource Extensions plug-in is designed to help you understand not only the basics of extending the capabilities of the workspace, but also how markers, natures, and builders function.

The plug-in manifest file defines the extension definitions for the different actions, markers, natures, builders, and other marker related processing such as help an quick fix support. These are the key classes from the com.ibm.jdg2e.resources.extensions package that are used to implement the examples just discussed.

Class (All) Description

RecentEditsRCL

This class tracks file changes and creates recent edit markers. This process is assisted by RecentEdits.

The preference and property pages that can be used to control this process are implemented by RecentEditsPreferencePage and RecentEditPropertyPage.

The preference values used are initialized by a preference initializer extension ( ValueDefaults).

CustomNature

Implements the nature extension. The nature will add the ReadmeBuilder to the project as a builder.

This builder uses a ReadmeVisitor to process the IResourceDelta provided to the builder.

When the builder detects an orphan .html file it creates a marker. The ReadmeResolutionGenerator will help resolve the problem marker.