Eclipse icon

Natures and Builders

The implementation of a nature and builder requires that you define them as extensions in your plug-in, provide an implementation of these extensions, and then either create projects that include the nature or add the nature to existing projects. The plugin.xml defines the extensions and the code is provided in the com.ibm.lab.soln.resources.nature_builder package. This example focuses on the use of the CustomNature and ReadmeBuilder.

Running the Solution

To run the example, launch the run-time instance of Eclipse (Run > Run As > Run-time Workbench).

  1. Create a project that includes the CustomNature by either:

    In either case, when the CustomNature is added to the project, its configure method is invoked to give it the opportunity to prepare the project. In this example, the configure method adds the ReadmeBuilder to the project.

    You can check if the nature and associated builder have been added to a project by opening the .project file or using one of the contributed project actions.

    Once the nature has been added to the project, and it has configured the builder, the builder will be invoked during build processing when changes have been made to resources in the project..

  2. Add a readme folder to the project.
    The ReadmeBuilder will process only the .readme files it finds in a readme folder.
    Note: The project structure action can be used to create the readme folder.

  3. Add a .readme file to the readme folder. If the Perform build automatically on resource modification Workbench preference is selected, a build will be triggered.

    The ReadmeBuilder build method is triggered when a build occurs. The build method determines what kind of build is being processed: full or incremental.
    The end result will be a corresponding .html file created for each modified .readme file, where the content of the .readme file is wrapped in simple HTML.

  4. Create a new simple project (simple.project), one that does not include the CustomNature or ReadmeBuilder, and then use the project structure action can to add a readme folder to this new project.

  5. Implement support for .readme file processing for the simple.project by teaching the existing ReadmeBuilder associated with the first project you created to reach out and process this new project. The ReadmeBuilder includes support for processing referenced projects, that is, those that are referenced by the project that includes the builder.

    So, to do this, open the Properties dialog for the first project and on the Project References page select the simple.project entry.

  6. Add a .readme file to the readme folder in the simple.project. Modify and save this file.

    The ReadmeBuilder for the first project will be invoked as it has resource deltas that it can process. Not for the project the builder is defined for, but for the projects it has registered interest in processing. The ReadmeBuilder will detect the .readme file modification and create a matching .html file.

Roadmap to the Solution

This example includes a nature and builder extension, a new project wizard, and several pop-up action contributions that demonstrate how natures and builders can be used to customize projects and process resources. the use of the workspace API. The extension definitions can be found in the plugin.xml. The classes that implement these extensions are shown below.

Extension Implementation
Nature:
Custom Nature
The nature is implemented by the CustomNature class.
Builder:
Readme Builder
The builder is implemented by the ReadmeBuilder class.
New project wizard:
New Project (w/CustomNature)
The wizard is implemented by the NewProjectWizard class.

When the nature is configured as part of a project it adds the builder. The builder implements a simple resource transformation by reacting to new or modified .readme files and creating associated .html files. This processing is implemented by the ReadmeVisitor class.

The com.ibm.lab.soln.resources.nature_builder package includes several contributed actions in the Navigator view that allow you to interact with the projects and their defined natures and builders:

Not all of these actions were referenced in the example instructions above. These actions provide the following function:

Pop-up Action Description / Implementation
Soln: Add Custom Nature Adds the CustomNature to the selected project.
ActionAddCustomNature implements this function.
Responds with the success or failure of the request.
Soln: Remove Custom Nature Removes the CustomNature from the selected project. This action is only shown if the selected project has the customer nature.
ActionRemoveCustomNature implements this function.
Responds with the success or failure of the request.
Soln: Add Builder Can be used to add the ReadmeBuilder directly to a project. This action will only add the builder if the CustomNature exists as part of the project (and the builder was previously removed).
ActionAddBuilderToProject
implements this function.
Responds with the success or failure of the request.
Soln: List Builders Lists the builders associated with the selected project.
ActionListBuilders implements this function.
Responds with the success or failure of the request.
Soln: Remove Builder Can be used to remove the ReadmeBuilder from the selected project. This action can remove a builder added by the CustomNature.
ActionRemoveBuilderFromProject implements this function.
Responds with the success or failure of the request.

© Copyright International Business Machines Corporation, 2003.
All rights reserved.