# 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:
   - Using the provided new project wizard to create a new project which will include the nature.
     Open the wizard using File > New > Project, selecting Soln: Resource Wizards and then New Project (w/CustomNature). Enter a project name. Select Finish to create the project. Message dialogs will confirm that the ReadmeBuilder and CustomNature have been added to the project.
   - Using the provided Add Custom Nature project pop-up menu choice to add the nature to an existing project.
     If you already have a project, you can add the CustomNature to that project by selection the project in the Navigator view and using the Soln: Resource Tools > Soln: Add CustomNature pop-up menu option.

   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.
   - A full build uses the `processFull` method to find out if a readme folder exists and processes any `.readme` files.
   - An incremental build uses the `processDelta` method to determine of the `IResourceDelta` contains any changes in a readme folder. If yes, this subset of the IResourceDelta is passed to the the `ReadmeVisitor` whose visit method then processes the IResourceDelta to find any `.readme` files.
   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.