What's New for 2.0?

This document describes the API changes that have been made in the Faceted Project Framework for WTP 2.0 release. Both Java API and extension point changes are covered. Note that the Faceted Project Framework API remains provisional for the 2.0 release. This means it will continue undergoing further significant changes in future release(s).

  1. Generics
  2. IProjectFacetVersion and IRuntimeComponentVersion Extend Comparable
  3. Requires Constraint Supports Groups
  4. Labels and Descriptions for Groups
  5. New IFacetedProject Validation API
  6. AddRemoveFacetsWizard Class Renamed to ModifyFacetedProjectWizard
  7. Extension Point Schema Changes to Work Around PDE Limitations
  8. Listeners and Events

1. Generics

All of the framework's API now use Java 5 generics. This has been done in a backwards compatible way and existing clients are expected to continue to work without any modifications. In order for a client to gain access to the type safety afforded by generics in this API, the client plugin's Java compiler level should be configured to be 5.0 or newer.

2. IProjectFacetVersion and IRuntimeComponentVersion Extend Comparable

The IProjectFacetVersion and IRuntimeComponentVersion interfaces now extend Comparable. Using the compareTo methods will yield significantly better performance than calling the version comparator directly on the version strings as the compareTo methods use pre-computed results and do not need to parse the version strings.

As part of this change, IVersionExpr.evaluate( String ) method has been replaced with IVersionExpr.check( Comparable ) method.

3. Requires Constraint Supports Groups

The requires constraint can now be declared using facet groups instead of individual facets. Any member of the group will satisfy the constraint. This allows a level of indirection so that a facet does not need to know about all of the group members.

Extension Point Changes

 
<extension point="org.eclipse.wst.common.project.facet.core.facets">
  <project-facet-version>
    <constraint>
      <requires group="group.id"/>
    </constraint>
  </project-facet-version>
<extension>

4. Labels and Descriptions for Groups

It is now possible to associate labels and description with groups. Note that groups are still automatically created on first use, so the use of the new group element is only necessary in order to specify the label and the description.

Extension Points Changes

 
<extension point="org.eclipse.wst.common.project.facet.core.facets">
  <group id="..."> (0 or more)
    <label>...</label>
    <description>...</description> (0 or 1)
  </group>
<extension>

Java API Changes

 
org.eclipse.wst.common.project.facet.core.IGroup
{
   String getLabel();
   String getDescription();
}

5. New IFacetedProject Validation API

There is now API for validating the faceted project. It allows the caller to find out about any problems with the project without searching for problem markers created by the faceted project validation builder. The validation builder now uses the new API.

Java API Changes

 
org.eclipse.wst.common.project.facet.core.IFacetedProject
{
   IStatus validate( IProgressMonitor monitor );
}

6. AddRemoveFacetsWizard Class Renamed to ModifyFacetedProjectWizard

The AddRemoveFacetsWizard class has been renamed to ModifyFacetedProjectWizard to align with terminology change being made in the rest of the system. The old class is deprecated, but still supported (extends the new class).

7. Extension Point Schema Changes to Work Around PDE Limitations

In order to work around false warnings reported by PDE's extension point schema validation, the following changes have been made to the framework's extension points. The old syntax is deprecated, but is still supported.

When declaring that a facet belongs to a category...

Old Syntax

 
<extension point="org.eclipse.wst.common.project.facet.core.facets">
  <project-facet>
    <category>...</category>
  </project-facet>
<extension>

New Syntax

 
<extension point="org.eclipse.wst.common.project.facet.core.facets">
  <project-facet>
    <member category="..."/>
  </project-facet>
<extension>

8. Listeners and Events

The existing facilities for listening on faceted project model changes have been re-designed to provide more information about the change that took place and to provide the same facility regardless of whether the client chooses to register the listener via direct API call or via an extension point.

In 1.5, extenders could either:

  1. Use IFacetedProject.addListener() method. Listener would get called when any aspect of faceted project model was changed, but the listener was not given any details about the change that took place.

  2. Use <event-handler> element of the org.eclipse.wst.common.project.facet.core.facets extension point to register an IDelegate implementation which is similar to how actions are implemented. This approach gave user a bit more control over what events to process as well as more information regarding what actually took place. However, not all changes could be surfaced via this interface due to limitations of the extension point and the IDelegate interface.

Full discussion of the new facility can be found here.

Java API Additions

 
org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener
{
    void handleEvent( IFacetedProjectEvent event );
}

org.eclipse.wst.common.project.facet.core.events.IFacetedProjectEvent
{
    enum Type
    {
        PROJECT_MODIFIED,
        PRE_INSTALL,
        POST_INSTALL,
        PRE_UNINSTALL,
        POST_UNINSTALL,
        PRE_VERSION_CHANGE,
        POST_VERSION_CHANGE,
        FIXED_FACETS_CHANGED,
        TARGETED_RUNTIMES_CHANGED,
        PRIMARY_RUNTIME_CHANGED
    }
    
    Type getType();
    IFacetedProject getProject();
}

org.eclipse.wst.common.project.facet.core.events.IFixedFacetsChangedEvent : IFacetedProjectEvent
{
    Set<IProjectFacet> getOldFixedFacets();
    Set<IProjectFacet> getNewFixedFacets();
}

org.eclipse.wst.common.project.facet.core.events.IProjectFacetActionEvent : IFacetedProjectEvent
{
    IProjectFacet getProjectFacet();
    IProjectFacetVersion getProjectFacetVersion();
    Object getActionConfig();
}

org.eclipse.wst.common.project.facet.core.events.IPrimaryRuntimeChangedEvent : IFacetedProjectEvent
{
    IRuntime getOldPrimaryRuntime();
    IRuntime getNewPrimaryRuntime();
}

org.eclipse.wst.common.project.facet.core.events.ITargetedRuntimesChangedEvent : IFacetedProjectEvent
{
    Set<IRuntime> getOldTargetedRuntimes();
    Set<IRuntime> getNewTargetedRuntimes();
}

org.eclipse.wst.common.project.facet.core.IFacetedProject
{
    ...
    void addListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener, IFacetedProjectEvent.Type... );
    void removeListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener );
    ...
}

org.eclipse.wst.common.project.facet.core.FacetedProjectFramework
{
    ...
    void addListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener, IFacetedProjectEvent.Type... );
    void removeListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener );
    ...
}

New Extension Point

 
<extension point="org.eclipse.wst.common.project.facet.core.listeners">
  <listener 
    class="{class:org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener}"
    eventTypes="{csv:org.eclipse.wst.common.project.facet.core.events.IFacetedProjectEvent.Type}"/> (1 or more)
<extension>

Deprecated Java API

 
org.eclipse.wst.common.project.facet.core.IFacetedProjectListener
{
    projectChanged();
}

org.eclipse.wst.common.project.facet.core.IFacetedProject
{
    ...
    void addListener( org.eclipse.wst.common.project.facet.core.IFacetedProjectListener );
    void removeListener( org.eclipse.wst.common.project.facet.core.IFacetedProjectListener );
    ...
}

org.eclipse.wst.common.project.facet.core.IRuntimeChangedEvent
{
    IRuntime getOldRuntime();
    IRuntime getNewRuntime();
}

Deprecated Extension Point

 
<extension point="org.eclipse.wst.common.project.facet.core.facets">
  ...
  <event-handler type="{string}" facet="{string}" version="{string}">
    <delegate class="{class:org.eclipse.wst.common.project.facet.core.IDelegate}"/>
  </event-handler>
  ...
<extension>