Helios System Requirements and Architecture

This document is tentative and subject to change without notice.

Themes

JSF 2.0 Support

The Helios release will introduce system level support for JSF 2.0.  This includes updates to:

1. Facet and library framework support for JSF 2.0 projects.
2. The XML catalog (after requisite IP review) for new XML schemas.
3. The application configuration EMF model (facesconfig) for new XML elements introduced in the release.
4. Supported web.xml configuration concepts.
5. The JSF Tag Registry, which will become the authoratative source of information about JSF tags (both JSP and Facelet).
6. Component tree rendering for the addition of the rendering target concept and an API to retrieve component ids that are in use.

New JSF 2.0 concepts to be supported by the system are:

1. Annotation-based configuration of JSF artifacts.
2. Implicit navigation rules formulated from supported action source tags.
3. Design time support for the JSF resource loading concept.
4. Facelet source editing support in the Structured Source Editor (SSE).

Flexibility of Adoption

Based on lessons learned over almost five years of experience with the JSF project as both committers and adopters, we have come to some conclusions about the limitations of our current bundling architecture with respect to adoption.  These are based on the following premises:

1. The most common, and therefore premier, adoption scenario is to create an update site that is installed directly on top of some subset of WTP and its dependencies.
   
2. Adopters may support other scenarios such as productizing, but they will still need to support option 1.
   
3. Frameworks that create long-lived objects or react to events without the adopter doing anything make it very difficult for adopters to tune their end-user experience. 
4. Only a choice few base platform features like JDT have become so "defacto standard" that adopters are comfortable exposing them to end users without significant customization.  WTP JSF Tools is not in this category.
   

This leads us to the following observations about adoption of the JSF Tools Project:

1. End-user visible features that appear by default are bad.  Examples include the appearance of the WPE action on the Open With action in the project explorer and the validation framework.  Once these features are contributed an adopter is stuck with them.  Short of doing hacky things like calling non-API methods or worse, calling setAccessible to get private data.  This is bad due to premise 1: adopters get stuck exposing things to their users that they may not like or conflict with a similar feature that they want to implement in their own way or based on a superior internal technology.
   
2. Frameworks that depend on non-overridable data such as JSF tag metadata are difficult to customize for same reason as observation 1.
   
3. Singletons make it difficult to extend a framework because it make things difficult to configure (generally singletons configure themselves) and control lifecycle (when do you dispose the singleton?).  This is bad due to premise 3.
   
4. Frameworks that use long-running processes, whether background or foreground, make it difficult for adopters to tune experience.  This is a problem due to premise 4.

Based on this analysis, we propose to change the bundling and system architecture in the following ways to improve adoptability:

1. Break up the JSF feature into smaller features.  Only the core feature will live in the SDK release.  The rest will be availabe in an optional download.
2. Eliminate singletons and replace them with relocatable services managed by OSGI.
3. Make all services configurable through pluggable factories.
4. Replace static method calls to services with object method calls that use constructor-based manual dependency injection to configure the service instance being used.

Bundling and Deployment Architecture

Feature Reorganization

The JSF feature is divided as follows:

JSF Core: All of the base functionailty required to support JSF tooling.  This feature will not expose any UI by default although it may contain resuable UI components.

Exemplary Features: All of the extensions and metadata required to extend JSF Core into basic exemplary features except for Faces Config Editor and Page Designer.

Faces Config Editor: The editor implementation.  Some of the reusable UI components such as artifact creation wizards will remain in JSF Core.

Page Designer (already exists): Of the plug-ins required for the WPE.

Replace Singletons with Relocatable Services

The following singletons is replaced with relocatable features.  Where the singleton is API, the access API for the singleton is depracated and changed to call the new service architecture:

Singleton	Description
MetadataModelManager	A per-project singleton for managing meta-data.
JSFAppConfigManager	A per-project singleton for managing application-wide JSF app config EMF models.
JSPModelProcessor	A per-file singleton that caches information about EL artifacts of interest.
ResourceBundleMapSource	A per-project singleton used to manage bundle files.
DesignTimeApplicationManager	A per-project singleton that manages simulated JSF objects.
CompositeTagRegistryFactory	A global factory for creating tag registries.

Make Services Factory Configurable

The following services will be made factory configurable:

Service	Change Description
Metadata	Introduce a Domain Context Factory that the framework will use to optionally delegate construction of each Model object to.  Current defaults will be maintained.
Metadata	Introduce Metadata Manager Factory that allows secondary in-memory repositories to be created.
JSF App Config	Introduce a Locator Provider Factory that the default JSF App Config Manager service uses to select which locators to use to find JSF App Config artifacts.  Current defaults will be maintained (note this means that adopters will need to specifically elect to find JSF 2.0 annotation-based and implicit navigation artifacts; this is done to allow tuning of performance).
JSF App Config	Introduce a Factory that allows additional configurations of the App Config Manager to be created.
Design Time Application Manager	Introduce a factory that allows optional delegation for creation of design application manager instances.Current defaults will be maintained.
ResourceBundleMapSource	Introduce a Factory that allows for optional construction of the map source objects through delegation.  Current defaults will be maintained.

Replace Static Method Calls to Services

Class	Framework
TraitValueHelper	Metadata Framework
TaglibDomainMetaDataQueryHelper	Metadata Framework

System Requirements

Locator Framework

The metadata and JSF app config frameworks both use similar but distinct locator concepts used to create an aggregation of artifacts from disparate sources.  We will centralize the concept of the locator in this release.  The conceptual design is as follows:

The Locator interface is parameterized based on the type of object that is returned.  Each locator also has following capabilities by default:

1. The ability to be started  and stopped.  Each start will include an initial context that may be used to initialize the locator.
2. The ability to fire events when the artifact set that the locator has locates has changed.

As shown, the existing metadata and app config locators will be refactored to be of this type.  Existing API will be deprecated but preserved where applicable.  The IJSFResourceLocator is also shown.

The general use of a locator is as follows:

JSF Resource Locators

JSF Resource Locators are a new concept introduced by JSF 2.0 that are used to find application resources at runtime.  JSF Tools will support design time APIs for finding resource-locatable artifacts in a JSF project based on the algorithm described in the spec section 2.6.  Resources may be:

1. In a web root relative directory called "resources". (2.6.1.1).
2. In any jar file on the class path in META-INF/resources (2.6.1.2).

Resource Identifier Parsing

An API will be defined that takes a String of the form:

[localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]

and parses into it's parts. The parser will include a validation step that can identify deviations from the specification that would cause the resource to be ignored at runtime per 2.6.1.3.

Querying Resource Libraries

An API will be defined that can be queried by resource identifier and returns available resource libraries in the search path for resource.  The query mechanism will simulate the algorithm described in 2.6.1.4.

Pluggability

The resource handler that converts resource identifiers into resources is pluggable. The framework will allow ToolDeveloper to replace the default resource handler with a custom one to match what is registered in an application.

Composite Component Resource Libraries

As provided in 10.3.2, resources in a composite sub-folder of a resources directory may be considered composite component libraries.  API will defined to find these libraries and include them in the JSF library registry. When querying resources by identifier, the result of any successful query will include information about the type resource including whether it is a composite component resource library

Application Configuration

New Locators

Two locators will be define that locate "virtual" faces config elements defined in annotations:

1. A locator that scans java source files in a project for @ManagedBean annotations and which collects these artifacts.
2. A locator that scans the view files in a project and searches for implicit navigations on action source attributes.

Because of the performance intensity of these locators, the application configuration manager will not be configured to use these by default.

New Application Configuration Model

The application configuration model will updated to handle all of the new app config file artifacts (XML elements) added in JSF 2.0.

New Superclass for Faces Config Nodes

All EMF objects representing Faces Config nodes will be made sub-classes of a new super-class that holds information pointing back to the source of the data.  The information will include:

1. The locator that discovered the node.
2. An IPath to the file that defines the node.
3. A marker or offset into the defining location where the node is declared.

Component Tree

Metadata

New meta-data will be added to support component tree construction from Facelet tags.

Construction Concepts

Support for the view facet that defines "render targets". This is necessary to be aware of components that are added relative h:head and h:body tags.

Component Id Management

The design time view root will have a new API method that can be used to get a list of all component ids in the view including the option to map back to the component/tag that uses the id. This method must be optimized for runtime performance since it is intended to be used by real time user features such as content assist.

JSF Tag Registry

A new tag registry will be added to support Facelet VDL tags.  This includes locating tag libraries in both the web.xml configured locations and in composite components.  Additionally, implicitly defined libraries must also be located in the jsf runtime.

New Locator

A new implementation of Locator will be defined for the purpose of finding these libraries.

Web.xml configuration API

New API will be created to directly get and set context param and other web.xml-specific options for JSF.

EL Framework

The EL framework will modified to support:

1. The new implicit variables.
2. The new scopes available for variables including the custom scope.  New scope maps will be added to the DTExternalContext.

Structured Source Editor Extensions

Content Type

A new content type will defined for the XHTML files containing default Facelet view definitions.  A content describer will be implemented to discover of a file containing XHTML content is in fact a Facelet file.  The algorithm may consider the current Facet installed on the owning project and/or defining user data in the project such as the presence of a WEB-INF/faces-config.xml or certain jars on the classpath.

Tag Metadata

Existing Libraries

New metadata is needed to cover off the new tags and attributes for existing tags in the h and f libraries:

<Gerry TODO: add list of new tags and new attributes on existing tags and discuss what metadata will be added for both>

New Libraries

JSF 2.0 introduces two new standard tag libraries: "ui" for standard Facelet page building and "composite" for defining custom components on the fly. The following metadata is needed for these libraries:

<Gerry TODO: add a list of all new tags and discuss what metadata will be added for each>