What's New for 2.0?

This document describes the API changes that have been made in the Faceted Project Framework for the WTP 2.0 release. Both Java API and extension point changes are covered. All API that was deprecated in this release is still supported, but clients are advised to switch to non-deprecated alternatives as soon as feasible.

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

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. Improvements to Presets

Significant improvements have been made to the presets facility for the 2.0 release. A new type of preset, referred to as a dynamic preset, is now available. A dynamic preset uses an extender-supplied factory to synthesize the preset definition on the fly based on the context in which it will be used. The "old-style" declarative presets are still available and are now referred to as static presets. Static presets have also been improved to allow them to extend other presets. A static preset can even extend a dynamic preset.

There is also a new preset that's part of the framework. It's a dynamic preset with id of "default.configuration" and whose contents are synthesized as follows:

1. If a runtime is selected, this preset will contain default facets as specified by IRuntime.getDefaultFacets(Set).
2. If no runtime is selected, this preset will contain default versions for all of the fixed facets as specified by IProjectFacet.getDefaultVersion().

New Extension Point

    <extension point="org.eclipse.wst.common.project.facet.core.presets">
      <static-preset id="{string}" extends="{string}">
        <label>{string}</label> (optional)
        <description>{string}</description> (optional)
        <facet id="{string}" version="{string}"/> (1 or more)
      </static-preset> (0 or more)
      <dynamic-preset id="{string}">
        <factory class="{class:org.eclipse.wst.common.project.facet.core.IPresetFactory}"/>
      </dynamic-preset> (0 or more)
    <extension>

Deprecated Extension Point

    <extension point="org.eclipse.wst.common.project.facet.core.facets">
      <preset id="{string}">
        <label>{string}</label> (optional)
        <description>{string}</description> (optional)
        <facet id="{string}" version="{string}"/> (1 or more)
      </preset> (0 or more)
    <extension>

Java API Additions

    interface org.eclipse.wst.common.project.facet.core.IPreset
    {
        enum Type { STATIC, DYNAMIC, USER_DEFINED }
        Type getType();
    }

    interface org.eclipse.wst.common.project.facet.core.IDynamicPreset extends IPreset
    {
        static final String CONTEXT_KEY_FIXED_FACETS;
        static final String CONTEXT_KEY_PRIMARY_RUNTIME;
        IPreset resolve( Map<String,Object> context );
    }

    interface org.eclipse.wst.common.project.facet.core.IPresetFactory
    {
        PresetDefinition createPreset( String presetId, Map<String,Object> context );
    }

    class org.eclipse.wst.common.project.facet.core.PresetDefinition
    {
        PresetDefinition( String label, String description, Set<IProjectFacetVersion> facets );
        String getLabel();
        String getDescription();
        Set<IProjectFacetVersion> getProjectFacets();
    }

    org.eclipse.wst.common.project.facet.core.FacetedProjectFramework
    {
        static final String DEFAULT_CONFIGURATION_PRESET_ID;
    }

Deprecated Java API

    interface org.eclipse.wst.common.project.facet.core.IPreset
    {
        boolean isUserDefined()
    }

3. 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.

4. 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>

5. 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();
    }

6. 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 );
    }

7. 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).

8. 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>

9. 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>

10. Miscellaneous

Java API Additions

    org.eclipse.wst.common.project.facet.core.IFacetedProject
    {
        boolean isTargetable( IRuntime runtime );
        boolean isTargeted( IRuntime runtime );
    }