[141591] Create a "What's New in 1.5" document for facets framew...
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/description.html b/docs/org.eclipse.wst.doc.isv/html/facets/description.html
new file mode 100644
index 0000000..eb6b2d3
--- /dev/null
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/description.html
@@ -0,0 +1,33 @@
+<!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>Checking WTP out</title>
+<link
+ rel="stylesheet"
+ type="text/css"
+ href="../sources/formate.css">
+</head>
+
+<body>
+<p class="ueberschrift">Faceted Project Framework</p>
+
+<p>The Faceted Project Framework allows the plugin developer to think of
+projects as composed of units of functionality, otherwise known as facets, that
+can be added and removed by the user.</p>
+
+<p>Project facets are most frequently used for adding natures, builders,
+classpath entries, and resources to a project.</p>
+
+<p>Primary Benefits</p>
+
+<ul>
+ <li>Consistent user experience.</li>
+ <li>Ability to accurately describe capabilities of the runtime platform.</li>
+</ul>
+
+</body>
+</html>
diff --git a/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew.html b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew.html
new file mode 100644
index 0000000..94f6634
--- /dev/null
+++ b/docs/org.eclipse.wst.doc.isv/html/facets/whatsnew.html
@@ -0,0 +1,332 @@
+<!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>Checking WTP out</title>
+<link
+ rel="stylesheet"
+ type="text/css"
+ href="../sources/formate.css">
+</head>
+
+<body>
+<p class="ueberschrift">What's New for 1.5?</p>
+
+<p>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).</p>
+
+<p><b>Attention:</b> 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.</p>
+
+<ol>
+ <li><a href="#vexprs">Version Expressions</a></li>
+ <li><a href="#actions">Action Definitions</a></li>
+ <li><a href="#wizard">Wizard Pages</a></li>
+ <li><a href="#event.handlers">Event Handlers</a></li>
+ <li><a href="#runtimes">Targeting Multiple Runtimes</a></li>
+ <li><a href="#presets">Descriptions for Presets</a></li>
+ <li><a href="#misc">Miscellaneous</a></li>
+</ol>
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="vexprs">1. Version Expressions</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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)".</p>
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="actions">2. Action Definitions</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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.</p>
+
+<p><u>Extension Points Changes</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">
+ ...
+ <action</font> id="string" <font color="#7B7B7B">... >
+ ...
+ </action>
+ ...
+<extension></font>
+</pre>
+</td></tr></table>
+
+<p><u>Java API Changes</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+org.eclipse.wst.common.project.facet.core.IActionDefinition
+{
+ String getId();
+ IProjectFacet getProjectFacet();
+ IVersionExpr getVersionExpr();
+ Action.Type getActionType();
+}
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IProjectFacetVersion
+{
+ ...</font>
+ IActionDefinition getActionDefinition( Action.Type type );
+ <font color="#7B7B7B">...
+}</font>
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.ProjectFacetsManager
+{
+ ...</font>
+ Set getActionDefinitions();
+ boolean isActionDefined( String id );
+ IActionDefinition getActionDefinition( String id );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="wizard">3. Wizard Pages</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>The extension point schema for defining wizard pages associated with the
+project facet actions has been revised to be more flexible.</p>
+
+<p><u>Deprecated Extension Point</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor=#FFF1C1>
+<pre>
+<extension point="org.eclipse.wst.common.project.facet.ui.wizard">
+ <wizard-pages facet="...">
+ <install> <i>(0 or 1)</i>
+ <page class="..."/> <i>(1 or more)</i>
+ </install>
+ <uninstall> <i>(0 or 1)</i>
+ <page class="..."/> <i>(1 or more)</i>
+ </uninstall>
+ </wizard-pages>
+</extension>
+</pre>
+</td></tr></table>
+
+<p><u>Replacement Extension Point</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<extension point="org.eclipse.wst.common.project.facet.ui.wizardPages">
+ <wizard-pages action="..."> <i>(1 or more)</i>
+ <page class="..."/> <i>(1 or more)</i>
+ </wizard-pages>
+</extension>
+</pre>
+</td></tr></table>
+
+<p>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.</p>
+
+<p><u>Deprecated Java API</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#FFF1C1">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.ui.ProjectFacetsUiManager
+{
+ ...</font>
+ List getWizardPages( Action.Type type, IProjectFacetVersion fv );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+<p><u>Replacement Java API</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.ui.ProjectFacetsUiManager
+{
+ ...</font>
+ List getWizardPages( String actionId );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="event.handlers">4. Event Handlers</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>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.</p>
+
+<p><u>Event Types</u></p>
+
+<p>PRE_INSTALL, POST_INSTALL, PRE_UNINSTALL, POST_UNINSTALL, PRE_VERSION_CHANGE,
+POST_VERSION_CHANGE, RUNTIME_CHANGED</p>
+
+<p><u>Extension Point Changes</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">
+ ...</font>
+ <event-handler type="..." facet="..." version="...">
+ <delegate class="..."/>
+ </event-handler>
+ <font color="#7B7B7B">...
+<extension></font>
+</pre>
+</td></tr></table>
+
+<p><u>RUNTIME_CHANGED Event</u></p>
+
+<p>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.</p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+org.eclipse.wst.common.project.facet.core.IRuntimeChangedEvent
+{
+ IRuntime getOldRuntime();
+ IRuntime getNewRuntime();
+}
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="runtimes">5. Targeting Multiple Runtimes</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>The ability for a project to target multiple runtimes has been further
+fleshed out during the 1.5 release.</p>
+
+<p><u>Deprecated Java API</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#FFF1C1">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IFacetedProject
+{
+ ...</font>
+ IRuntime getRuntime();
+ void setRuntime( IRuntime runtime );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+<p><u>Replacement Java API</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IFacetedProject
+{
+ ...</font>
+ 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 );
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="presets">6. Descriptions for Presets</a></font></p>
+<!-- ********************************************************************** -->
+
+<p>It is now possible to associate description with presets.</p>
+
+<p><u>Extension Points Changes</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">
+ ...
+ <preset>
+ ...</font>
+ <description>...</description> <i>(0 or 1)</i>
+ <font color="#7B7B7B">...
+ </preset>
+ ...
+<extension></font>
+</pre>
+</td></tr></table>
+
+<p><u>Java API Changes</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.ProjectFacetsManager
+{
+ ...</font>
+ IPreset definePreset( String name, String description, Set facets );
+ <font color="#7B7B7B">...
+}</font>
+
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IPreset
+{
+ ...</font>
+ String getDescription();
+ <font color="#7B7B7B">...
+}</font>
+</pre>
+</td></tr></table>
+
+
+<!-- ********************************************************************** -->
+<p><font size="+1"><a name="misc">7. Miscellaneous</a></font></p>
+<!-- ********************************************************************** -->
+
+<p><u>Java API Changes</u></p>
+
+<table cellpadding="10"><tr><td width="10"> </td><td bgcolor="#E2E2E2">
+<pre>
+<font color="#7B7B7B">org.eclipse.wst.common.project.facet.core.IProjectFacetVersion
+{
+ ...</font>
+ boolean isValidFor( Set fixed );
+ boolean conflictsWith( IProjectFacetVersion fv );
+ String getPluginId();
+ <font color="#7B7B7B">...
+}</font>
+
+org.eclipse.wst.common.project.facet.core.IVersionExpr
+{
+ String toDisplayString();
+}
+</pre>
+</td></tr></table>
+
+<p></p>
+
+</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 bc2b63f..51164bd 100644
--- a/docs/org.eclipse.wst.doc.isv/toc_WST.xml
+++ b/docs/org.eclipse.wst.doc.isv/toc_WST.xml
@@ -99,6 +99,12 @@
href="html/plugin_descriptions_WST/org.eclipse.wst.javascript.ui.html" />
-->
</topic>
+ <topic label="Faceted Project Framework"
+ href="html/facets/description.html">
+ <topic label="What's New for 1.5?"
+ href="html/facets/whatsnew.html">
+ </topic>
+ </topic>
<topic label="Relational Database (RDB) Tools"
href="html/plugin_descriptions_WST/rdb.html">
<!--