[113542] [UI] Investigate other ways to present facet description
[117789] [UI] Add/Remove project facets should provide button to c...
[150261] [UI] Facet selection table needs better column distribution
[157206] IFacetedProjectListener should describe the change that h...
[159025] Illegal extension schema markup in project-facet
[159121] Can't remove facet and select runtime
[159529] FPF: Version expressions should support unknown versions
[164456] Provide Mechanism to Expand Facet Category
[173380] Faceted Project Framework and Java 5
[173525] [UI] Improve handling of unchecking fixed facet
[175744] add a getRuntime() method to org.eclipse.wst.common.proje...
[115349] [UI] Improve rendering of facet version selection
[137825] Facet RuntimeManager should support localized runtime names
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/listeners.html b/docs/org.eclipse.wst.doc.isv/html/facets/listeners.html
new file mode 100644
index 0000000..a9c725c
--- /dev/null
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/listeners.html
@@ -0,0 +1,296 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+<html>
+
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <title>Listening for Changes to Faceted Projects</title>
+ <link type="text/css" rel="stylesheet" href="tutorial/tutorial.css"/>
+</head>
+
+<body>
+
+<style type="text/css">
+
+ .subHeader
+ {
+ font-size: 16px;
+ font-weight: bold;
+ }
+
+ .eventsTableHeaderCell
+ {
+ font-weight: bold;
+ border-bottom: 1px solid #000000;
+ padding: 2px;
+ }
+
+ .eventsTableTypeCell
+ {
+ vertical-align: top;
+ padding-top: 2px;
+ padding-bottom: 2px;
+ padding-left: 2px;
+ padding-right: 20px;
+ }
+
+ .eventsTableInterfaceCell
+ {
+ vertical-align: top;
+ padding-top: 2px;
+ padding-bottom: 2px;
+ padding-left: 2px;
+ padding-right: 20px;
+ }
+
+ .eventsTableDescriptionCell
+ {
+ vertical-align: top;
+ padding: 2px;
+ }
+
+</style>
+
+<h1 align="center">Listening for Changes to Faceted Projects</h1>
+
+<p>The Faceted Project Framework provides a facility that will notify any interested parties when
+a change is made to the model of a faceted project. Listeners can be registered either via a direct
+API call or via an extension point. Listeners can be global or scoped to a specific project.</p>
+
+<p class="subHeader">Events</p>
+
+<table style="border-collapse:collapse">
+
+ <tr>
+ <td class="eventsTableHeaderCell">Event Type</td>
+ <td class="eventsTableHeaderCell">Event Object Interface</td>
+ <td class="eventsTableHeaderCell">Description</td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">PROJECT_MODIFIED</td>
+ <td class="eventsTableInterfaceCell">IFacetedProjectEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered when faceted project metadata is modified in any way. No detailed information
+ about the change is provided. Note that while listening for PROJECT_MODIFIED events is
+ guaranteed to catch all other events, the inverse is not true. Listing on all the other
+ events is not guaranteed to catch all PROJECT_MODIFIED events. This is because there are
+ circumstances when the system does not have the details about the type of the change
+ (such as when the faceted project metadata file is modified on disk).
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">PRE_INSTALL</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered right before a facet is installed.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">POST_INSTALL</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td>Gets triggered right after a facet is installed.</td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">PRE_UNINSTALL</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered right before a facet is uninstalled.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">POST_UNINSTALL</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered right after a facet is uninstalled.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">PRE_VERSION_CHANGE</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered right before a facet version is changed.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">POST_VERSION_CHANGE</td>
+ <td class="eventsTableInterfaceCell">IProjectFacetActionEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered right after a facet version is changed.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">FIXED_FACETS_CHANGED</td>
+ <td class="eventsTableInterfaceCell">IFixedFacetsChangedEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered when project's fixed facets are changed.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">TARGETED_RUNTIMES_CHANGED</td>
+ <td class="eventsTableInterfaceCell">ITargetedRuntimesChangedEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered when the set of runtimes that the project targets is changed.
+ </td>
+ </tr>
+
+ <tr>
+ <td class="eventsTableTypeCell">PRIMARY_RUNTIME_CHANGED</td>
+ <td class="eventsTableInterfaceCell">IPrimaryRuntimeChangedEvent</td>
+ <td class="eventsTableDescriptionCell">
+ Gets triggered when the primary targeted runtime of the project is changed.
+ </td>
+ </tr>
+
+</table>
+
+<p class="subHeader">Registering a Listener</p>
+
+<p>All listeners have to implement <code>IFacetedProjectListener</code> interface which looks like
+this:</p>
+
+<div class="code">
+<pre class="java-code"><span class="java-keyword">package</span> org.eclipse.wst.common.project.facet.core.events;
+
+<span class="java-keyword">public interface</span> IFacetedProjectListener
+{
+ <span class="java-keyword">void</span> handleEvent( IFacetedProjectEvent event );
+}
+</pre>
+</div>
+
+<p>Depending on the event type, it may be possible to cast the event object to a more specific
+interface in order to get details about the event. See the event table for information about which
+event object interface corresponds with which event type.</p>
+
+<p>There are three ways to register a listener:</p>
+
+<ol>
+ <li>IFacetedProject.addListener()</li>
+ <li>FacetedProjectFramework.addListener()</li>
+ <li>Extension Point: org.eclipse.wst.common.project.facet.core.listeners</p>
+</ol>
+
+<p>All of these methods allows you to specify which events the listener should be notified about.
+Not specifying event types on registration will cause the listener to be notified about all events.
+This is typically not desired. If a listener needs to react to any change in the project and has no
+need to analyze specific events, it should be registered for the <code>PROJECT_MODIFIED</code>
+event.</p>
+
+<p>The first method registers a listener that is scoped to a specific project. The last two
+register a global listener which will be notified about changes in all faceted projects that are
+present in the workspace. In most circumstances, if a global listener is needed, it should be
+registered via the extension point rather than using <code>FacetedProjectFramework.addListener()</code>
+API. Using the extension point guarantees that the listener will not miss any events due to not
+being registered early enough. It also delays initialization of the plugin bundle containing the
+listener until an event that the listener is interested in is fired.</p>
+
+<p class="subHeader">Extension Point</p>
+
+<p>The extension point that's used for registering listeners is quite simple. Only two pices of
+information need to be supplied: the listener class name and an optional list of event types.</p>
+
+<div class="code">
+<pre class="xml-code"><extension point="<span class="code-text">org.eclipse.wst.common.project.facet.core.listeners</span>">
+ <listener
+ class="<span class="code-text">{class:org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener}</span>"
+ eventTypes="<span class="code-text">{event.types}</span>"/> <i>(1 or more)</i>
+<extension>
+</pre>
+</div>
+
+<p>The <code>eventTypes</code> attribute value should be a comma-separated list of event types.</p>
+
+<p class="subHeader">Examples</p>
+
+<p>This example registers a very simple listener that prints out events received. The listener is
+registered several different ways for the purposes of this example.</p>
+
+<div class="code">
+<pre class="java-code"><span class="java-keyword">package</span> com.mycorp.myproduct;
+
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.events.IFacetedProjectEvent;
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener;
+
+<span class="java-keyword">public final class</span> ListenerImpl <span class="java-keyword">implements</span> IFacetedProjectListener
+{
+ <span class="java-keyword">public void</span> handleEvent( <span class="java-keyword">final</span> IFacetedProjectEvent event )
+ {
+ System.out.println( event.toString() );
+ }
+}
+</pre>
+</div>
+
+<p>The following code snippet registers the above listener on a specific project to listen for
+changes in the runtimes that the project targets.</p>
+
+<div class="code">
+<pre class="java-code"><span class="java-keyword">import</span> org.eclipse.core.resources.IProject;
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.IFacetedProject;
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.ProjectFacetsManager;
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.events.IFacetedProjectEvent;
+
+...
+
+IProject pj;
+
+...
+
+<span class="java-keyword">final</span> IFacetedProject fpj = ProjectFacetsManager.create( pj );
+<span class="java-keyword">final</span> ListenerImpl listener = <span class="java-keyword">new</span> ListenerImpl();
+
+fpj.addListener( listener,
+ IFacetedProjectEvent.Type.TARGETED_RUNTIMES_CHANGED,
+ IFacetedProjectEvent.Type.PRIMARY_RUNTIME_CHANGED );
+
+...
+
+fpj.removeListener( listener );
+</pre>
+</div>
+
+<p>The following code snippet register the above listener to listen for the PRE_INSTALL and
+PRE_UNINSTALL events in all faceted projects.</p>
+
+<div class="code">
+<pre class="java-code"><span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.FacetedProjectFramework;
+<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.events.IFacetedProjectEvent;
+
+...
+
+<span class="java-keyword">final</span> ListenerImpl listener = <span class="java-keyword">new</span> ListenerImpl();
+
+FacetedProjectFramework.addListener( listener,
+ IFacetedProjectEvent.Type.PRE_INSTALL,
+ IFacetedProjectEvent.Type.PRE_UNINSTALL );
+
+...
+
+FacetedProjectFramework.removeListener( listener );
+</pre>
+</div>
+
+<p>The following code snippet accomplishes the same thing as the one above, except it does this
+via the extension point.</p>
+
+<div class="code">
+<pre class="xml-code"><extension point="<span class="code-text">org.eclipse.wst.common.project.facet.core.listeners</span>">
+ <listener class="<span class="code-text">com.mycorp.myproduct.ListenerImpl</span>" eventTypes="<span class="code-text">PRE_INSTALL,PRE_UNINSTALL</span>"/>
+<extension>
+</pre>
+</div>
+
+<br/><br/><br/><br/>
+
+</body>
+
+</html>
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/tutorial/tutorial.html b/docs/org.eclipse.wst.doc.isv/html/facets/tutorial/tutorial.html
index f22936e..e2dc7fe 100644
--- a/docs/org.eclipse.wst.doc.isv/html/facets/tutorial/tutorial.html
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/tutorial/tutorial.html
@@ -82,9 +82,8 @@
10. <a href="#summary">Summary</a><br/>
Appendix A: <a href="#custom.version.comparators">Custom Version Comparators</a><br/>
Appendix B: <a href="#version.expressions">Version Expressions</a><br/>
-Appendix C: <a href="#event.handlers">Event Handlers</a><br/>
-Appendix D: <a href="#property.tester">Property Tester</a><br/>
-Appendix E: <a href="#wizard.context">Wizard Context</a><br/>
+Appendix C: <a href="#property.tester">Property Tester</a><br/>
+Appendix D: <a href="#wizard.context">Wizard Context</a><br/>
</div>
<h2><a name="getting.started">1. Getting Started</a></h2>
@@ -1066,90 +1065,7 @@
</pre>
</div>
-<h2><a name="event.handlers">Appendix C: Event Handlers</a></h2>
-
-<p>It is possible to register listeners for certain events in the faceted
-project's life cycle. Here is the list of the available events:</p>
-
-<div class="code">
-<pre class="java-code">PRE_INSTALL
-POST_INSTALL
-PRE_UNINSTALL
-POST_UNINSTALL
-PRE_VERSION_CHANGE
-POST_VERSION_CHANGE
-RUNTIME_CHANGED
-</pre>
-</div>
-
-<p>The way one declares event handlers is very similar to how actions are
-declared, however there are some key differences:</p>
-
-<ul>
-
- <li><p>Unlike actions, events are not a direct result of something a user does.
- This means that it is not possible to associate wizard pages or provide a
- custom configuration object for event handlers.</p></li>
-
- <li><p>Multiple event handlers can be declared for the same event. The relative
- order that they will be invoked in is not specified.</p></li>
-
-</ul>
-
-<p>Here is the extension point schema for registering event handlers:</p>
-
-<div class="code">
-<pre class="code-xml"><span class="context-code"><extension point="org.eclipse.wst.common.project.facet.core.facets"></span>
- <event-handler facet="<span class="schema-type">{string}</span>" version="<span class="schema-type"><span class="schema-type-link">{<a href="#version.expressions">version.expr</a>}</span></span>" type="<span class="schema-type">{event.type}</span>">
- <delegate class="<span class="schema-type">{class:org.eclipse.wst.common.project.facet.core.IDelegate}</span>"/>
- </action>
-<span class="context-code"></extension></span>
-</pre>
-</div>
-
-<p>As you can see, just like with action definitions, the event handler has to
-implement the <code>IDelegate</code> interface. Also, just like with action
-definitions, the <code><event-handler></code> block can be embeded directly
-inside the <code><project-facet-version></code> element. In that case,
-the values for the <code>facet</code> and <code>version</code> attributes are
-implied and the attributes should be omitted.</p>
-
-<p>The <code>PRE_*</code> and <code>POST_*</code> event handlers all get the
-same config object passed into their delegate's <code>execute</code> method
-as the corresponding action delegate. The <code>RUNTIME_CHANGED</code> event
-handlers get an instance of <code>IRuntimeChangedEvent</code>.</p>
-
-<div class="code">
-<pre class="java-code"><span class="java-keyword">package</span> org.eclipse.wst.common.project.facet.core;
-
-<span class="java-keyword">import</span> org.eclipse.wst.common.project.facet.core.runtime.IRuntime;
-
-<span class="java-comment">/**
- * Describes the runtime changed event to the RUNTIME_CHANGED event handlers.
- */</span>
-
-<span class="java-keyword">public interface</span> IRuntimeChangedEvent
-{
- <span class="java-comment">/**
- * Returns the runtime previously associated with the project.
- *
- * <span class="java-javadoc-keyword">@return</span> the runtime previously associated with the project, or <code>null</code>
- */</span>
-
- IRuntime getOldRuntime();
-
- <span class="java-comment">/**
- * Returns the runtime that's now associated with the project.
- *
- * <span class="java-javadoc-keyword">@return</span> the runtime that's now associated with the project, or <code>null</code>
- */</span>
-
- IRuntime getNewRuntime();
-}
-</pre>
-</div>
-
-<h2><a name="property.tester">Appendix D: Property Tester</a></h2>
+<h2><a name="property.tester">Appendix C: Property Tester</a></h2>
<p>A property tester is provided by the Faceted Project Framework that allows
the presence of the facet in a project to be tested by any extension point that
@@ -1181,7 +1097,7 @@
</pre>
</div>
-<h2><a name="wizard.context">Appendix E: Wizard Context</a></h2>
+<h2><a name="wizard.context">Appendix D: Wizard Context</a></h2>
<p>Sometimes it desirable to be able to adjust the behavior of facet action
wizard pages based on user input in the wizard pages of other facets. The
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew150.html b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew150.html
index f1d5086..68a0278 100644
--- a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew150.html
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew150.html
@@ -5,7 +5,7 @@
<meta
http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
-<title>Checking WTP out</title>
+<title>What's New for 1.5?</title>
<link
rel="stylesheet"
type="text/css"
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew151.html b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew151.html
index 3eb7458..c3d37d5 100644
--- a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew151.html
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew151.html
@@ -5,7 +5,7 @@
<meta
http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
-<title>Checking WTP out</title>
+<title>What's New for 1.5.1?</title>
<link
rel="stylesheet"
type="text/css"
@@ -43,7 +43,7 @@
<font color="#7B7B7B"><extension point="org.eclipse.wst.common.project.facet.core.facets">
<project-facet></font>
<default-version version="{string}"/> <i>(optional)</i>
- <default-version version="{class:org.eclipse.wst.common.project.facet.core.IDefaultVersionProvider}"/> <i>(optional)</i>
+ <default-version provider="{class:org.eclipse.wst.common.project.facet.core.IDefaultVersionProvider}"/> <i>(optional)</i>
<font color="#7B7B7B"></project-facet>
<extension></font>
</pre>
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew20.html b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew20.html
index 03f76b4..3db9c15 100644
--- a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew20.html
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew20.html
@@ -5,7 +5,7 @@
<meta
http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
-<title>Checking WTP out</title>
+<title>What's New for 2.0?</title>
<link
rel="stylesheet"
type="text/css"
@@ -22,16 +22,29 @@
further significant changes in future release(s).</p>
<ol>
+ <li><a href="#generics">Generics</a></li>
<li><a href="#comparable">IProjectFacetVersion and IRuntimeComponentVersion Extend Comparable</a></li>
<li><a href="#requires-group">Requires Constraint Supports Groups</a></li>
<li><a href="#group-labels">Labels and Descriptions for Groups</a></li>
<li><a href="#validate">New IFacetedProject Validation API</a></li>
<li><a href="#new-wizard-class">AddRemoveFacetsWizard Class Renamed to ModifyFacetedProjectWizard</a></li>
+ <li><a href="#pde-limitations">Extension Point Schema Changes to Work Around PDE Limitations</a></li>
+ <li><a href="#listeners">Listeners and Events</a></li>
</ol>
<!-- ********************************************************************** -->
-<p><font size="+1"><a name="#comparable">1. IProjectFacetVersion and IRuntimeComponentVersion Extend Comparable</a></font></p>
+<p><font size="+1"><a name="#generics">1. Generics</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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.</p>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="#comparable">2. IProjectFacetVersion and IRuntimeComponentVersion Extend Comparable</a></font></p>
<!-- ********************************************************************** -->
<p>The IProjectFacetVersion and IRuntimeComponentVersion interfaces now extend
@@ -45,7 +58,7 @@
<!-- ********************************************************************** -->
-<p><font size="+1"><a name="#requires-group">2. Requires Constraint Supports Groups</a></font></p>
+<p><font size="+1"><a name="#requires-group">3. Requires Constraint Supports Groups</a></font></p>
<!-- ********************************************************************** -->
<p>The requires constraint can now be declared using facet groups instead of
@@ -69,7 +82,7 @@
<!-- ********************************************************************** -->
-<p><font size="+1"><a name="group-labels">3. Labels and Descriptions for Groups</a></font></p>
+<p><font size="+1"><a name="group-labels">4. Labels and Descriptions for Groups</a></font></p>
<!-- ********************************************************************** -->
<p>It is now possible to associate labels and description with groups. Note that
@@ -103,7 +116,7 @@
<!-- ********************************************************************** -->
-<p><font size="+1"><a name="validate">4. New IFacetedProject Validation API</a></font></p>
+<p><font size="+1"><a name="validate">5. New IFacetedProject Validation API</a></font></p>
<!-- ********************************************************************** -->
<p>There is now API for validating the faceted project. It allows the caller to
@@ -124,7 +137,7 @@
<!-- ********************************************************************** -->
-<p><font size="+1"><a name="new-wizard-class">5. AddRemoveFacetsWizard Class Renamed to ModifyFacetedProjectWizard</a></font></p>
+<p><font size="+1"><a name="new-wizard-class">6. AddRemoveFacetsWizard Class Renamed to ModifyFacetedProjectWizard</a></font></p>
<!-- ********************************************************************** -->
<p>The AddRemoveFacetsWizard class has been renamed to ModifyFacetedProjectWizard
@@ -132,7 +145,191 @@
class is deprecated, but still supported (extends the new class).</p>
-<p></p>
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="pde-limitations">7. Extension Point Schema Changes to Work Around PDE Limitations</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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.</p>
+
+<p>When declaring that a facet belongs to a category...</p>
+
+<p><u>Old Syntax</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B"><extension point="org.eclipse.wst.common.project.facet.core.facets">
+ <project-facet></font>
+ <category>...</category>
+ <font color="#7B7B7B"></project-facet>
+<extension></font>
+</pre>
+</td></tr></table>
+
+<p><u>New Syntax</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B"><extension point="org.eclipse.wst.common.project.facet.core.facets">
+ <project-facet></font>
+ <member category="..."/>
+ <font color="#7B7B7B"></project-facet>
+<extension></font>
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="listeners">8. Listeners and Events</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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.</p>
+
+<p>In 1.5, extenders could either:</p>
+
+<ol>
+
+ <li>Use <code>IFacetedProject.addListener()</code> 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.<br/><br/></li>
+
+ <li>Use <code><event-handler></code> element of the
+ <code>org.eclipse.wst.common.project.facet.core.facets</code> extension point to register an
+ <code>IDelegate</code> 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 <code>IDelegate</code> interface.</li>
+
+</ol>
+
+<p>Full discussion of the new facility can be found <a href="listeners.html">here</a>.</p>
+
+<p><u>Java API Additions</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+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();
+}
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IFacetedProject
+{
+ ...</font>
+ void addListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener, IFacetedProjectEvent.Type... );
+ void removeListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener );
+ <font color="#7B7B7B">...
+}</font>
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.FacetedProjectFramework
+{
+ ...</font>
+ void addListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener, IFacetedProjectEvent.Type... );
+ void removeListener( org.eclipse.wst.common.project.facet.core.events.IFacetedProjectListener );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+<p><u>New Extension Point</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<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}"/> <i>(1 or more)</i>
+<extension>
+</pre>
+</td></tr></table>
+
+<p><u>Deprecated Java API</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor=#FFF1C1>
+<pre>
+org.eclipse.wst.common.project.facet.core.IFacetedProjectListener
+{
+ projectChanged();
+}
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IFacetedProject
+{
+ ...</font>
+ void addListener( org.eclipse.wst.common.project.facet.core.IFacetedProjectListener );
+ void removeListener( org.eclipse.wst.common.project.facet.core.IFacetedProjectListener );
+ <font color="#7B7B7B">...
+}</font>
+
+org.eclipse.wst.common.project.facet.core.IRuntimeChangedEvent
+{
+ IRuntime getOldRuntime();
+ IRuntime getNewRuntime();
+}
+</pre>
+</td></tr></table>
+
+<p><u>Deprecated Extension Point</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#FFF1C1">
+<pre>
+<font color="#7B7B7B"><extension point="org.eclipse.wst.common.project.facet.core.facets">
+ ...</font>
+ <event-handler type="{string}" facet="{string}" version="{string}">
+ <delegate class="{class:org.eclipse.wst.common.project.facet.core.IDelegate}"/>
+ </event-handler>
+ <font color="#7B7B7B">...
+<extension></font>
+</pre>
+</td></tr></table>
</body>
</html>
diff --git a/docs/org.eclipse.wst.doc.isv/toc_WST.xml b/docs/org.eclipse.wst.doc.isv/toc_WST.xml
index e790844..555c37f 100644
--- a/docs/org.eclipse.wst.doc.isv/toc_WST.xml
+++ b/docs/org.eclipse.wst.doc.isv/toc_WST.xml
@@ -25,6 +25,9 @@
<topic label="Tutorial"
href="html/facets/tutorial/tutorial.html">
</topic>
+ <topic label="Listening for Changes to Faceted Projects"
+ href="html/facets/listeners.html">
+ </topic>
<topic label="Enabling UI Elements Based on Project Facets"
href="html/facets/enabling-based-on-facets.html">
</topic>