Project natures

Project natures allow a plug-in to tag a project as a specific kind of project. For example, the Java development tools (JDT) use a "Java nature" to add Java-specific behavior to projects.� Project natures are defined by plug-ins, and are typically added or removed per-project when the user performs some action defined by the plug-in.

A project can have more than one nature.� However, when you define a project nature, you can define special constraints for the nature:

• one-of-nature - specifies that the nature is one of a named set.� Natures in a set are mutually exclusive; that is, only one nature belonging to the set can exist for a project.
• requires-nature - specifies that the nature depends on another nature and can only be added to a project that already has the required nature.

To implement your own nature, you need to define an extension and supply a class which implements IProjectNature.

Defining a nature

The org.eclipse.core.resources.natures extension point is used to add a project nature definition. The following markup adds a nature for the hypothetical com.example.natures plug-in.

The class identified in the extension must implement the platform interface IProjectNature. This class implements plug-in specific behavior for associating nature-specific information with a project when the nature is configured.

   public class MyNature implements IProjectNature {

      private IProject project;

      public void configure() throws CoreException {
         // Add nature-specific information
         // for the project, such as adding a builder
         // to a project's build spec.
      }
      public void deconfigure() throws CoreException {
         // Remove the nature-specific information here.
      }
      public IProject getProject() {
         return project;
      }
      public void setProject(IProject value) {
         project = value;
      }
   }

The configure() and deconfigure() methods are sent by the platform when natures are added and removed from a project.� You can implement the configure() method to add a builder to a project as discussed in Builders.

Associating the nature with a project

Defining the nature is not enough to associate it with a project.� You must assign a nature to a project by updating the project's description to include your nature.� This usually happens when the user creates a new project with a specialized new project wizard that assigns the nature.� The following snippet shows how to assign our new nature to a given project.

   try {
      IProjectDescription description = project.getDescription();
      String[] natures = description.getNatureIds();
      String[] newNatures = new String[natures.length + 1];
      System.arraycopy(natures, 0, newNatures, 0, natures.length);
      newNatures[natures.length] = "com.example.natures.mynature";
      description.setNatureIds(newNatures);
      project.setDescription(description, null);
   } catch (CoreException e) {
      // Something went wrong
   }

NOTE: The nature id is the fully qualified id of the nature extension. The fully qualified id of an extension is created by combining the plug-in id with the simple extension id in the plugin.xml file. For example, a nature with simple extension id "mynature" in the plug-in "com.example.natures" would have the name "com.example.natures.mynature"

The natures are not actually assigned to (and configured) for the project until you set the project description into the project.� Also note that the identifier used for the nature is the fully qualified name (plug-in id + extension id) of the nature extension.

If the nature has been defined with constraints, then workspace API can be used to validate the new nature.� For example, suppose a nature is defined with a prerequisite:

   id="myOtherNature"
      name="My Other Nature">
      
         
         
      
   
   

The new nature is not valid unless the first nature exists for the project.� Depending on the design of your plug-in, you may want to check whether the prerequisite nature has been installed, or you may want to add the prerequisite nature yourself.� Either way, you can check on the validity of proposed combinations of project natures using workspace API.

   try {
      IProjectDescription description = project.getDescription();
      String[] natures = description.getNatureIds();
      String[] newNatures = new String[natures.length + 1];
      System.arraycopy(natures, 0, newNatures, 0, natures.length);
      newNatures[natures.length] = "com.example.natures.myOtherNature";
      IStatus status = workspace.validateNatureSet(newNatures);

      // check the status and decide what to do
      if (status.getCode() == IStatus.OK) {
      	description.setNatureIds(newNatures);
      	project.setDescription(description, null);
      } else {
      	// raise a user error
	...
      }
   } catch (CoreException e) {
      // Something went wrong
   }

Nature descriptors

In addition to working with natures by their id, you can obtain the descriptor (IProjectNatureDescriptor) which describes a nature, its constraints, and its label.� You can query a particular nature for its descriptor, or get descriptors from the workspace.� The following snippet gets the project nature descriptor for our new nature:

      IProjectNatureDescriptor descriptor = workspace.getNatureDescriptor("com.example.natures.myOtherNature");

You can also get an array of descriptors for all installed natures:

      IProjectNatureDescriptor[] descriptors = workspace.getNatureDescriptors();