What's New for 1.5?

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

Attention: All Java API and extension points that have been deprecated in the 1.5 release will be removed in the 2.0 release. Until that point they will continue to function and be fully supported.

1. Version Expressions
2. Action Definitions
3. Wizard Pages
4. Event Handlers
5. Targeting Multiple Runtimes
6. Descriptions for Presets
7. Miscellaneous

1. Version Expressions

Version expressions are used in various context throughout the framework's extension points and Java API when multiple versions need to be specified. In the 1.0.x release, the vesion expressions were of the form "<1.5,2.3,2.5,>=5.0", where commas indicate a disjunction (or). This syntax did not allow ranges to be specified and was unwieldy due to the need to escape the angle brackets in the plugin.xml files. So this syntax has been deprecated in the 1.5 release. The new syntax also uses commas to specify a disjunction, but now ranges can be specified using "[1.3-6.3)" notation. Square brackets mean inclusive, while parenthesis mean exclusive. Open ranges can also be specified using notation like "[1.3" and "6.3)".

2. Action Definitions

Action definitions have been made into first class entities with the new ability to be assigned an id and the creation of the browsing API. In addition, it is now possible to create constrained VERSION_CHANGE actions in order to designate precisely which versions the delegate is capable of changing from. Multiple VERSION_CHANGE delegates with different "from.versions" constraint can be specified.

Extension Point Changes

    <extension point="org.eclipse.wst.common.project.facet.core.facets">
      ...
      <action id="string" ... >
        ...

        <property name="from.versions" value="string"/> (0 or 1)

        ...
      </action>
      ...
    <extension>

Java API Additions

    org.eclipse.wst.common.project.facet.core.IActionDefinition
    {
       static final String PROP_FROM_VERSIONS;
       String getId();
       IProjectFacet getProjectFacet();
       IVersionExpr getVersionExpr();
       Action.Type getActionType();
       Map getProperties();
       Object getProperty( String name );
       Object createConfigObject( IProjectFacetVersion fv, String pjname );
    }

    org.eclipse.wst.common.project.facet.core.IProjectFacetVersion
    {
       ...
       boolean supports( Set base, Action.Type type );
       Set getActionDefinitions();
       Set getActionDefinitions( Action.Type type );
       IActionDefinition getActionDefinition( Set base, Action.Type type );
       ...
    }

    org.eclipse.wst.common.project.facet.core.ProjectFacetsManager
    {
        ...
        Set getActionDefinitions();
        boolean isActionDefined( String id );
        IActionDefinition getActionDefinition( String id );
        ...
    }

Deprecated Java API

    org.eclipse.wst.common.project.facet.core.IProjectFacetVersion
    {
       ...
       boolean supports( Action.Type type );
       Object createActionConfig( Action.Type type, String pjname );
       boolean isSameActionConfig( Action.Type type, IProjectFacetVersion fv );
       ...
    }

3. Wizard Pages

The extension point schema for defining wizard pages associated with the project facet actions has been revised to be more flexible.

Deprecated Extension Point

    <extension point="org.eclipse.wst.common.project.facet.ui.wizard">
      <wizard-pages facet="...">
        <install> (0 or 1)
          <page class="..."/> (1 or more)
        </install>
        <uninstall> (0 or 1)
          <page class="..."/> (1 or more)
        </uninstall>
      </wizard-pages>
    </extension>

Replacement Extension Point

    <extension point="org.eclipse.wst.common.project.facet.ui.wizardPages">
      <wizard-pages action="..."> (1 or more)
        <page class="..."/> (1 or more)
      </wizard-pages>
    </extension>

Note the new extension point id. The "action" attribute should contain the action that these pages are to be associated with. The action id can be explicitly specified via the new "id" attribute available on the "action" element of the core facets extension point. If not specified, the default id is generated using the "[facet-id]#[version-expression]#[action-type]" pattern.

Deprecated Java API

    org.eclipse.wst.common.project.facet.ui.ProjectFacetsUiManager
    {
       ...
       List getWizardPages( Action.Type type, IProjectFacetVersion fv );
       ...
    }

Replacement Java API

    org.eclipse.wst.common.project.facet.ui.ProjectFacetsUiManager
    {
       ...
       List getWizardPages( String actionId );
       ...
    }

4. Event Handlers

A new event handling facility has been added. This makes for a clear separation between actions (user initiated), and events (automatic). Prior to this change it was possible to register a "runtime-changed" action. That usage is now deprecated and should be converted to use event handler extension point. Various new events have also been added.

Event Types

PRE_INSTALL, POST_INSTALL, PRE_UNINSTALL, POST_UNINSTALL, PRE_VERSION_CHANGE, POST_VERSION_CHANGE, RUNTIME_CHANGED

Extension Point Changes

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

RUNTIME_CHANGED Event

In the 1.0.x release it was possible to register a "runtime-changed" action. That usage is now deprecated and should be converted into a RUNTIME_CHANGED event handler. The RUNTIME_CHANGED event handler delegate gets passed in a config object that carries additional information about the event.

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

5. Targeting Multiple Runtimes

The ability for a project to target multiple runtimes has been further fleshed out during the 1.5 release.

Deprecated Java API

    org.eclipse.wst.common.project.facet.core.IFacetedProject
    {
       ...
       IRuntime getRuntime();
       void setRuntime( IRuntime runtime );
       ...
    }

Replacement Java API

    org.eclipse.wst.common.project.facet.core.IFacetedProject
    {
       ...
       Set getTargetedRuntimes();
       void setTargetedRuntimes( Set runtimes, IProgressMonitor monitor );
       void addTargetedRuntime( IRuntime runtime, IProgressMonitor monitor );
       void removeTargetedRuntime( IRuntime runtime, IProgressMonitor monitor );
       IRuntime getPrimaryRuntime();
       void setPrimaryRuntime( IRuntime runtime, IProgressMonitor monitor );
       ...
    }

6. Descriptions for Presets

It is now possible to associate description with presets.

Extension Points Changes

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

Java API Changes

    org.eclipse.wst.common.project.facet.core.ProjectFacetsManager
    {
       ...
       IPreset definePreset( String name, String description, Set facets );
       ...
    }

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

7. Miscellaneous

Java API Changes

    org.eclipse.wst.common.project.facet.core.IProjectFacetVersion
    {
       ...
       boolean isValidFor( Set fixed );
       boolean conflictsWith( IProjectFacetVersion fv );
       String getPluginId();
       ...
    }

    org.eclipse.wst.common.project.facet.core.IVersionExpr
    {
       boolean evaluate( String version );
       String toDisplayString();
    }