JSF Tools Helios Requirements

Change Log

Most recent change to the top:

2010/02/17: Expand supported JavaEE containers back to JavaEE 5.

Terminology and Notation

The following terms are defined for use in this document:

JSFDeveloper refers to a use case actor who develops JSF applications. This actor is the primary "end-user" of the tooling. JSFDeveloper has a basic grasp of Java, JavaEE web tier and JSF programming basics. JSFDeveloper doesn't create new tooling.

ToolDeveloper refers to a use case actor who adopts and extends the JSF tools framework. ToolDeveloper has an in-depth knowledge of both Eclipse development and the JSF specification. ToolDeveloper makes use of provided extension points and Java API to create custom tooling using the framework.

JSF 2.0 Requirements

Facelet Development

JSF 2.0 adds support for multiple "View Declaration Languages (VDL)" (section 7.6). A VDL is a format by which a JSF view (page) is declared. In JSF 1.X, the only choice supported in the spec was JSP, although through the pluggable view handler facility, others could be added. Facelets are included in JSF 2.0 as the new default VDL for JSF. Per section 10.1, "New features introduced in version 2 and later are only exposed to page authors using Facelets." Facelets uses XHTML instead of JSP as the default XML format for describing views. It also supports two richer view-building formats: templates and composites.

A template, as the name suggests, allows many pages to be defined by having one or more base template files in which individual view instances override some sections but keep others. For example, the template may define a header, left and right menu bars and a footer for all pages; each instance of the template might simply override the middle section with custom content.

A composite is a JSF component that is defined using similar XHTML markup to those used for views. A JSFDeveloper creates a new composite by "composing" one or more other components into a new component. JSF 2.0 introduces a new schema for defining composites through XML composite files.

XHTML source editing

The JSFDeveloper shall be able to do source-level development of Facelet XHTML view files with similar capabilities as are found in the current JSF/JSP source level editor.

These capabilities will include:

1. Validation and content assist for referenced library namespaces. Namespaces can be defined either explicitly through the Facelet taglib facility or implicitly through the detection of composites through the resource loading facility.
2. Validation and content assist for tags declared for use in a Facelet view by use of namespace inclusion. Certain limitations may exist compared to the comparable JSP editing feature because Facelets has lower minimum requirements for tag meta-data. The framework will provide an extensible mechanism by which additional metadata may be added to fill gaps in required metadata. All sources of tag metadata defined in the spec shall also be supported.
3. Validation and content assist for tag attributes. Same as section on tags.
4. Validation and content-assist for tag attribute values.
5. Validation and content assist for EL expressions inside tag attribute values.
6. Hyperlink and hover help for namespaces, tags, attributes and EL expressions.

In addition, the following source editing capabilities shall be supported that are not necessarily guaranteed for JSP:

1. Validation, content assist, hyperlink and hover help support for EL expressions used in XML text nodes.
2. Tag support for the basic Facelet (http://java.sun.com/jsf/facelets), new core (http://java.sun.com/jsf/core), new html (http://java.sun.com/jsf/html), composite component and (??) JSTL subset tags and tag libraries.
3. Support for namespaces declared through the composite component mechanism as discovered through the resource loading facility.

Composite Component Development

JSFDeveloper shall be able to do regular schema-based development of composite components. This includes but may not be limited to the inclusion of the requisite schemas in the XML catalog. The framework will provide a tag library interface to all components defined using the composite mechanism.

JSFDeveloper shall be able to create new Composite Component files in a directed way (i.e. wizard).

Taglib support

JSFDeveloper shall be able to access all libraries defined in his project according to the JSF 2.0 specification through:

1. Declaration in the web.xml file per Section 11.1.3 of the spec.
2. Implicit discovery of all files with the name pattern "META-INF/*.taglib.xml" on the class path.

JSFDeveloper will be able to create new taglib file and at a minimum have schema-based source editing of the files.

Application Configuration

JSF 2.0 introduces two major new themes in application configuration: XML file reduction and Resource Loading.

The XML file reduction theme consists of a combination of features intended to simplify the amount of application data that is needed in the faces-config file. Two main new features are added to support this: Annotation-based Artifact Declaration and Simplified Navigation.

The Resource Loading features adds a new facility that allows automatic discovery of application artifacts through an implicit look-up mechanism. This feature is used both implicitly by the system to find composites and is explicitly exposed to the JSFDeveloper for use in finding application resources such as string bundles and images.

Annotation-based Artifact Declaration

JSF 2.0 adds several annotations that my be added to artifact classes. The artifacts supported by the specification per section 11.5.1 are:

1. FacesComponent: same as <component> tag; class must extend UIComponent.
2. FacesConverter: same as <converter> tag; class must extend Converter.
3. FacesRenderer: same as <renderer> tag; class must extended Renderer.
4. FacesValidator: same as <validator> tag; class must extend Validator.

In addition, the spec supports a set of annotations for declaring managed beans. This specification is separate from the main spec in anticipation of a more common JavaEE annotation spec for declaring such beans.

ToolDeveloper shall be provided API to discover all of the above artifacts as though they had been declared in a faces-config file. ToolDeveloper shall be able determine where the artifact was declared.

Simplified Navigation

JSF 2.0 adds two new navigation concepts to help simplify the control of applications. "Implicit Navigation" is a mechanism by which an automatic navigation rule is created from view X to view Y when the literal value of an action executed in view X is the name of view Y. "Conditional Navigation" allows JSFDeveloper to specify a new "if" element inside <navigation-rule> configurations to use EL expressions to control view transitions.

JSFDeveloper shall have access to implicit navigations in all features that currently support explicit navigation rules, except as stated below under explicit exclusions. Conditional navigations shall be visually decorated where possible to indicate that they are conditional. This decoration shall include the EL expression in use.

ToolDeveloper shall have access programmatically to the known implicit navigation's in an application as though they are explicit navigation's. The API shall also provide information about where the implicit navigation is defined. ToolDeveloper shall have access to information about the conditionality of all explicit navigation's.

Resource Loading

The resource loading facility (section 2.6) defined by JSF 2.0 allows both the system and the application developer to discover application artifacts at runtime. Per section 2.6.1, resources can be discovered in two ways: by searching the sub-directories of a directory called "resources" in the web application root and by searching the META-INF/resources directory of each jar on the classpath. Resources in these locations are organized by "library name" according to the name of the sub-directory of the "resources" folder where they reside.

ToolDeveloper shall be provided API that returns all of the discoverable resource libraries in a source project. Included in the information about each such resource library will be a reference back to where it was defined.

The JSF runtime uses the resource loading facility to find composite components.

ToolDeveloper shall be provided API that can narrow the search for resource libraries to those containing composite components. JSFDeveloper shall have access to all tag libraries defined through this mechanism in all of the ways JSP TLD-defined tag libraries are exposed (caveat: outages may occur where insufficient meta-data is required by the Facelet spec compared to the TLD-spec).

Section 2.6.1.3 of the spec describes a resource locator format for referencing resources.

ToolDeveloper shall be provided an API that constructs and parsers this resource locator format. The API for finding discoverable resources libraries shall allow query using the parsed data structure for the locator reference format.

New Schema Elements

JSF 2.0 introduces a number of new schema elements.

ToolDeveloper shall have access to all new schema elements through the EMF interface.

Component Tree

JSF tools can create a simulated design time tree of components that are expected to be created for a given view at runtime. This tree stores basic component meta-data based on the JSF tag registry.

Component Ids

The importance of component ids has increased in JSF 2.0.

ToolDeveloper shall be able to query a list of all component ids used in a Facelets or JSP view.

Render Targets

The design time view root needs to be enhanced to include support for "component resources", which are linked to target areas for rendering purposes. The two built-in target areas defined in the spec are "head" (created by the use of h:head in place of head) and "body" (created by the use of h:body in place of body).

ToolDeveloper shall be able to query a list of default targets (head and body) used in a document including which sections and component tree elements they apply to. ToolDeveloper will also be able to add metadata that defines additional target areas and links additional (or existing) tags to the creation of such areas similar to h:head and h:body.

Misc

New web.xml flags

JSF 2.0 introduces a number of new options in the web.xml file.

javax.faces.DISABLE_FACELET_JSF_VIEWHANDLER -- if set to true, disables the facelet viewhandler and reverts view functionality to be equivalent to JSF 1.2. ToolDeveloper shall have access to get and set this flag through new API.

javax.faces.FACELETS_LIBRARIES -- a semi-colon separated list of facelet libraries. JSFDeveloper shall see any valid entries added here added to available libraries. ToolDeveloper shall have API that parses this option if present and returns a list of such references in a usable form.

javax.faces.PROJECT_STAGE -- a human-readable string describing one of possible set of enumerated development stages. JSFDeveloper shall be able to set this value, defaulted to DEVELOPMENT, when a new web project is created. ToolDeveloper shall have API to access this parameter.

New implicit symbols

JSF 2.0 adds several new implicit variables to all EL expressions:

resource -- the current resource handler from facesContext.getApplication().getResourceHandler().

component -- the last component pushed on the component stack using UIComponent.pushComponentToEL()

cc -- the component returned from UIComponent.getCurrentCompositeComponent()

viewScope -- scope map for the new "View Scope". facesContext.getViewRoot().getViewMap()

flash -- scope map for the new "Flash Scope". getExternalContext.getFlash()

JSFDeveloper shall have access to these variables in all features where implicit variables are currently available.

New Scopes

Three new scopes have been added: view, flash and custom. View and Flash, are specifically supported in all implementations. The custom scope allows a developer to create a new dynamic scope.

JSFDeveloper shall see view and flash scopes available in all places currently supported for other built-in scopes (i.e. request), including the faces-config editor. ToolsDeveloper shall be able to manipulate design time scopes and scope maps in the same way he currently manipulates other built-in scopes.

Custom scopes shall be seamlessly translated into scopes based on the scope name configuration. That is, if a project contains a configuration for a custom scope called "foo" (either through faces-config or annotation), then "foo" will appear as if it is a built-in scope for that project.

Project Configuration

JSFDeveloper shall be able to configure dynamic web projects, both new and existing, as being JSF 2.0 projects. This is subject to existing versioning and other constraints (e.g. JSF 2.0 may only be applied to JavaEE 5 and later projects).

Explicitly Excluded

The following functional areas are considered out of scope for this release and should therefore be considered explicitly excluded from these requirements. These exclusions should be considered to hold precedence over any other requirements which seen to be in conflict:

1. tag support for JSTL and JSTL function libraries introduced in Facelets are explicitly excluded.
2. support javascript functionality is explicitly excluded. Ajax functionality is only supported in terms tag metadata for the f:ajax tag.
3. Implicit navigation support shall not be added to the Faces-Config navigation editor.