Project Facets Extension Point

org.eclipse.wst.common.project.facet.core.facets

This is the main extension point in the faceted project framework. It is used for defining project facets. A project facet can be thought of as a unit of functionality that the user can add to the project when the functionality is needed.

<!ELEMENT extension (project-facet | project-facet-version | category | preset | template | action | event-handler | group)+>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>

(no description available)



<!ELEMENT label (#PCDATA)>

The localizable name that is presented to the user. If not specified, the id will be used for a label.



<!ELEMENT description (#PCDATA)>

The description text.



<!ELEMENT and (and | or | requires | conflicts)+>

A facet constraint operator that performs a conjunction over the results of evaluation of two or more sub-expressions. This operator will return true if and only if all sub-expressions evaluate to true.



<!ELEMENT or (and | or | requires | conflicts)+>

A facet constraint operator that performs a disjunction over the results of evaluation of two or more sub-expressions. This operator will return true if any of the sub-expressions evaluate to true.



<!ELEMENT requires EMPTY>

<!ATTLIST requires

group   CDATA #IMPLIED

facet   CDATA #IMPLIED

version CDATA #IMPLIED

soft    (true | false) >

A facet constraint operator that is used to declare a dependency of one facet on another facet or any member of a group of facets. This operator will return true if the dependency is satisfied. Note that the group attribute should not be used together with the facet and version attributes.



<!ELEMENT conflicts EMPTY>

<!ATTLIST conflicts

group   CDATA #IMPLIED

facet   CDATA #IMPLIED

version CDATA #IMPLIED>

A facet constraint operator that is used to declare a conflict between this facet and another facet or this facet and a group of facets. This operator will return true if and only if the conflict is not present. Note that the group attribute should not be used together with the facet and version attributes.



<!ELEMENT constraint (and | or | requires | conflicts)>

Specifies the constraint that has to be satisfied before this facet can be installed in a project. A constraint can be used to specify dependencies on other facets as well as conflicts.



<!ELEMENT group-member EMPTY>

<!ATTLIST group-member

id CDATA #REQUIRED>

Makes this facet a member of the group specified in the id attribute. A facet can be a member of any number of groups. Groups are auto-created when referenced by this extension point. The facet groups are primarily used when specifying conflict constraints.



<!ELEMENT project-facet (label? , description? , version-comparator? , default-version? , member?)>

<!ATTLIST project-facet

id CDATA #REQUIRED>

Declares a project facet. A project facet can be thought of as a unit of functionality that the user can add to the project when the functionality is needed. Note that a facet need to have a least one version declared in order to be useful. See project-facet-version for more details.



<!ELEMENT project-facet-version (constraint? , group-member* , action* , event-handler*)>

<!ATTLIST project-facet-version

facet   CDATA #REQUIRED

version CDATA #REQUIRED>

Declares a project facet version. Each facet needs to have at leas one version declared in order to be useful.



<!ELEMENT version-comparator EMPTY>

<!ATTLIST version-comparator

class CDATA #REQUIRED>

Specifies the version comparator for this project facet. If no version comparator is specified the default comparator will be used. The default version comparator can handle versions that are written in standard decimal notation.



<!ELEMENT category (label? , description?)>

<!ATTLIST category

id CDATA #REQUIRED>

Declares a project facets category. Categories are groups of facets that the user will typically want to add or remove as a set.



The preset element is deprecated

<!ELEMENT preset (label , description? , facet)>

<!ATTLIST preset

id CDATA #REQUIRED>

Declares a preset. A preset represents a common configuration of facets and their versions that a user might want to utilize on several projects. Presets can be supplied via this extension point or created by the user.



<!ELEMENT template (label , fixed , preset)>

<!ATTLIST template

id CDATA #REQUIRED>

Declares a template. A template is simply a combination of fixed facets and an optional preset. Templates are used as a guide when creation projects.



<!ELEMENT action (config-factory? , delegate , property*)>

<!ATTLIST action

type    (install|uninstall|version-change|runtime-changed|INSTALL|UNINSTALL|VERSION_CHANGE)

facet   CDATA #IMPLIED

version CDATA #IMPLIED

id      CDATA #IMPLIED>

Provides implementation of an action, such as install or uninstall, that a user can take on a project facet. Any action that's not implemented will not be available to the user. The action element can be used standalone or embeded inside the project-facet-version element. If used inside the project-facet-version element, the facet and version attributes are implied and should not be specified.



<!ELEMENT config-factory EMPTY>

<!ATTLIST config-factory

class CDATA #REQUIRED>

Specifies the factory that will construct a configuration object to be used for parameterizing the action delegate. A configuration object is not necessary if the delegate does not require parameterization.



<!ELEMENT delegate EMPTY>

<!ATTLIST delegate

class CDATA #REQUIRED>

Specifies the delegate that should be invoked when an action or an event happens.



The event-handler element is deprecated

<!ELEMENT event-handler (delegate)>

<!ATTLIST event-handler

type    (PRE_INSTALL|POST_INSTALL|PRE_UNINSTALL|POST_UNINSTALL|PRE_VERSION_CHANGE|POST_VERSION_CHANGE|RUNTIME_CHANGED)

facet   CDATA #IMPLIED

version CDATA #IMPLIED>

Adds an event handler for one of the events in the faceted project life cycle. The event-handler element can be used standalone or embeded inside the project-facet-version element. If used inside the project-facet-version element, the facet and version attributes are implied and should not be specified.

Deprecation Notes: This part of the facets extension point is deprecated. The org.eclipse.wst.common.project.facet.core.listeners extension point should be used instead.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  (from.versions)

value CDATA #REQUIRED>

Specifies an action property.



<!ELEMENT default-version EMPTY>

<!ATTLIST default-version

version  CDATA #IMPLIED

provider CDATA #IMPLIED>

Used to provide the facet version that should be selected by default. If a default version is not specified, the latest version will be used. Note that if a runtime is selected, the runtime can override this default with a version best suited for that runtime. The default can be specified either statically by using the version attribute or dynamically by implementing the org.eclipse.wst.common.project.facet.core.IDefaultVersionProvider interface and using the provider attribute.



<!ELEMENT group (label , description?)>

<!ATTLIST group

id CDATA #REQUIRED>

Describes a project facet group. A group is a named collection of project facet versions. It is used primarily as a parameter to the "requires" and "conflicts" constraints and allows a level of indirection where a facet does not need to know about all the members of the group. A given project facet version can belong to several groups. Groups are created automatically when used in the "group-member" element, so an explicit group declaration is optional. However, it does allow a label and a description to be associated with the group.



<!ELEMENT member EMPTY>

<!ATTLIST member

category CDATA #REQUIRED>

Adds the project facet as a member of a category.



The following example illustrates the various facilities exposed by this extension point. This example is taken from the Building Project Facets tutorial.

<extension point=

"org.eclipse.wst.common.project.facet.core.facets"

>

<category id=

"formgen.category"

>

<label>

FormGen

</label>

<description>

Enables generation of HTML forms based on XML definition files.

</description>

</category>

<project-facet id=

"formgen.core"

>

<label>

FormGen Core

</label>

<description>

Enables generation of HTML forms based on XML definition files.

</description>

<category>

formgen.category

</category>

</project-facet>

<project-facet-version facet=

"formgen.core"

version=

"1.0"

>

<constraint>

<requires facet=

"jst.web"

version=

"2.2,2.3,2.4"

/>

</constraint>

<action type=

"INSTALL"

id=

"formgen.core.install"

>

<config-factory class=

"com.formgen.eclipse.FormGenCoreFacetInstallConfig$Factory"

/>

<delegate class=

"com.formgen.eclipse.FormGenCoreFacetInstallDelegate"

/>

</action>

</project-facet-version>

<project-facet id=

"formgen.ext"

>

<label>

FormGen Extensions

</label>

<description>

Enables additional FormGen widgets.

</description>

<category>

formgen.category

</category>

</project-facet>

<project-facet-version facet=

"formgen.ext"

version=

"1.0"

>

<constraint>

<requires facet=

"formgen.core"

version=

"1.0"

/>

</constraint>

<action type=

"INSTALL"

>

<delegate class=

"com.formgen.eclipse.FormGenExtFacetInstallDelegate"

/>

</action>

</project-facet-version>

<preset id=

"formgen.preset"

>

<label>

FormGen Web Project

</label>

<description>

Creates a web project with FormGen functionality.

</description>

<facet id=

"jst.java"

version=

"5.0"

/>

<facet id=

"jst.web"

version=

"2.2"

/>

<facet id=

"formgen.core"

version=

"1.0"

/>

<facet id=

"formgen.ext"

version=

"1.0"

/>

</preset>

</extension>