Faceted Project Framework provides a powerful mechanism for extending the capabilities of the Web Tools Platform. Project facets are typically used as a way of adding functionality to a project. When a facet is added to the project it can perform any necessary setup actions such as copying resources, installing builders, adding natures, etc. Facets can also be used as markers for enabling user interface elements.
Some of the readers may be wondering how facets are different from the project natures which are supported by the Eclipse platform. Natures are designed to be hidden from user's view. They are essentially markers that are set behind the scenes by tooling. Project facets, on the other hand, have been designed from the ground up to be manipulated by the end users. The Faceted Project Framework provides all the necessary user interface elements for managing the facets on a project and since facets are self describing the user is prevented from creating invalid configurations. Basically, it is no longer necessary to write custom project creation wizards or the "Enable Feature X" menu actions. Common way of managing which facets are installed on a project means less burden on the plugin writer and better end user experience.
This tutorial covers the extension points and Java API that are used for creating project facets. The reader is assumed to be already familiar with developing plugins for Eclipse and to have user-level knowledge of the Web Tools Platform.
You are a developer for a company which develops a product called FormGen. FormGen is basically a servlet that generates HTML forms based on XML definition files. The product is composed of a jar containing the servlet and some basic widgets. There is also an add-on jar with some extra widgets. Users have been manually adding the jars into the WEB-INF/lib directories of their web projects and setting up the servlet definitions in web.xml by hand. Your task is to make this setup easier by writing a couple of project facets that will perform these actions automatically.
To follow along with this tutorial, you will need to have a working install of Web Tools Platform v1.5. The tutorial is not designed to be used with 1.0.x version of WTP as there are numerous extension point and API differences. You can download the install kits for WTP and its prerequisites, including Eclipse Platform v3.2, at the following locations:
Once the required
software has been installed you will need to create a new workspace and add the starter project to it. The starter project includes the materials and utility code that will be used in this tutorial. If you get stuck at any point you can take a peek at the solution project.
Project facets are declared via the org.eclipse.wst.common.project.facet.core.facets extension point. This is a pretty large extension point with lots of facilities, but we will start small and progress incrementally while building the tutorial facets. Here is the part of the schema that we will be working with initially:
As you can see, there are two top-level elements in this part of the extension point schema. The <project-facet> element is used to declare the facet itself. The <project-facet-version> element is used to declare versions of the facet. Every facet implementation needs to provide at least one facet version declaration. In fact, as you will see later in this tutorial, the bulk of the work happens in the <project-facet-version> declaration. For now all you need to remember is that a facet cannot be used unless it has at least one version.
Insert the above code into your plugin.xml file and lets see it in action. Launch Eclipse with your FormGen plugin and then open the Dynamic Web Project wizard. Make sure that <none> is selected in the Target Runtime field on the first page and go to the second page. You should see a screen that looks like the following. Note that the FormGen facets that you have created are displayed.
One of the problems with what we have so far is that the FormGen facets appear in other module project wizards such as the EJB Project Wizard. That, of course, makes no sense since FormGen is servlet-based technology and so is only applicable to J2EE web applications. To solve this problem we will use the constraint mechanism to specify the dependencies.
Here is what that part of the extension point schema looks like:
As you can see, the constraint is an expression tree and you have four operators at your disposal. Lets go over them one by one.
The requires operator is the most frequently used of all the operators. It is used to specify a dependency on another facet. If the version attribute is not specified, any version of the referenced facet will satisfy the constraint. If only specific versions will do, the version attribute can contain a version expression.
The soft attribute is used to create a special kind of a dependency. Facet selection will not be prevented if the dependency is not met, but if the dependency is met, the facet is guaranteed to be installed after the referenced facet.
The conflicts constraint is used to indicate that the declaring facet will not work correctly if installed into the same project as referenced facets. The conflicts constraint comes in two flavors. You can either specify a conflict with a single facet or with a group of facets.
What are groups of facets? Facet groups are a way to designate a conflict with a certain class of facets without having to list all of the facets explicitly. For instance, the WTP module facets all belong to the "modules" group. They also each declare a conflict with the "modules" group. This prevents two module facets from being installed into the same project. By declaring a conflict with a group whose membership can expand as necessary, third parties can add module facets on top of WTP and have the new facets interact correctly with the built-in module facets.
A facet group is created the first time a facet declares group membership. H