Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

---

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.

   <extension
      point="org.eclipse.core.resources.natures"
      id="mynature"
      name="My Nature">
      <runtime>
         <run class="com.example.natures.MyNature">
         </run>
      </runtime>
   </extension>

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:

   <extension
      point="org.eclipse.core.resources.natures"
      id="myOtherNature"
      name="My Other Nature">
      <runtime>
         <run class="com.example.natures.MyOtherNature">
         </run>
      </runtime>
   <requires-nature id="com.example.natures.mynature"/>
   </extension>

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(natures);

      // 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();