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.
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.
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:
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 |
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> |
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:
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.<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> |
Java API Additions
org.eclipse.wst.common.project.facet.core.IFacetedProject { boolean isTargetable( IRuntime runtime ); boolean isTargeted( IRuntime runtime ); } |