# The Design Time Application Manager

### Overview

The Design Time Application Manager (DTAppMgr), defines the early stages of a mechanism to simulate JSF runtime state conditions at design time. While it is not intended to replace a runtime simulator, it provides an extensible framework to allow adopters to provide end-user features that depend on simulating certain specific runtime behavior. These features include validation and content assist for EL expressions.
The DTAppMgr is comprised of the following main components:

- a simulated FacesContext, called DTFacesContext, used to simulates part of this key runtime context object.
- a pluggable ExternalContext, called DTExternalContext to support different behaviors in different containers (i.e. JSP).
- pluggable resolvers for EL variables, properties and methods including default implementations.
- a JSP processor that can update simulated design time state based on a JSP page and tag-based meta-data.

### The simulated FacesContext

The simulated FacesContext, called DTFacesContext, currently supports a very limited subset of the runtime FacesContext object. Its main function is to allow for a pluggable external context. At design-time, one FacesContext is created per IFile.

### Pluggable ExternalContext

The ExternalContext is used to separate container-dependent context information from the rest of the FacesContext. At design time, we support a DTExternalContext with much the same function. This external context can be configured by adopters by implementing a factory extension point. The extension point is org.eclipse.jst.jsf.designtime.externalcontext. You extension will define an id and class. The id uniquely identifies you factory class, which must extend org.eclipse.jst.jsf.designtime.internal.provisional.context.AbstractDTExternalContextFactory. To set your external context factory as the current one, use DesignTimeApplicationManager.setExternalContextProvider(String). Note that by changing the current ExternalContextProvider on a project, you will significantly change the behavior of how variables are resolved in EL expressions.

### Pluggable resolvers

JSF EL expressions may contain variable and method bindings that reference external objects. At runtime, this is accomplished through several mechanisms that convert different types of identifier symbols into objects and methods. At design-time the JSF tooling tries to parallel these as closely as possible. These mechanisms are:

- VariableResolver
- PropertyResolver
- MethodBinding

#### VariableResolver

All identifier symbol resolution in EL starts with the VariableResolver. An expression like "myBean.property" is resolved by first extracting the symbol "myBean" and requesting the VariableResolver to return a matching runtime object. At design time, we parallel this exactly but constructing a design-time description of the object rather than its actual value (since the actual value cannot be fully computed until runtime in most cases). The concept of a "DTVariableResolver" is introduced. A default implementation is automatically provided which closely mirrors the default runtime resolver. New variable resolvers can be contributed through the Eclipse extension point mechanism to support custom runtime counterparts. To learn more about contributing new variables, see Contributing EL Variables.

#### PropertyResolver

Once a variable is resolved, the next step in resolving a value binding is to resolve its properties. To return to our simple example, "myBean.property", the JSF runtime will pass the object returned for 'myBean' to the property resolver along with the name 'property' and ask it to resolve it to an object. At design time, we parallel this by introducing the "DTPropertyResolver".

#### MethodBinding

The method binding mechanism implemented by the JSF runtime, differs from the way variables and properties are resolved. At design time however, we support them in the same way by providing a "DTMethodResolver". The main reason for this divergence is that at runtime, the method binding need know only enough to invoke a method. However at design time, we want to be able resolve a method binding in such a way that we can provide the same kinds of features we provide for properties such as signature validation and content assist.

### JSP document processor

The JSP document processor parses JSP document models looking for information to update in the simulated design time. The primary objective of the processor is to allow component writers to add support for tags that contribute EL variables. They can accomplish this by contributing JSF tooling meta-data for a particular uri/element/attribute that defines such a variable. The meta-data properties that are supported are as follows:

Meta-data property | Valid Values | Description
contributes-value-binding | true or false | This property alerts the model processor that this attribute contributes a variable to the EL name space at runtime. If no further meta-data is provided, this will cause a default variable using the text of the attribute as the name to be added to the name space for this document at 'request' scope. The variable will have no properties or methods. More information about the variable can be provided using the extra meta-data defined below.
value-binding-scope | 'request', 'session', 'application' | This property will set the runtime scope for the contribute variable. The default is 'request' if not provided.
value-binding-symbol-factory | An corresponding to a 'factoryId' field on a valid extension of 'org.eclipse.jst.jsf.context.symbol.contextSymbolFactory'. | If you wish to customize the variable created for this attribute, you can specify this factory extension. Your factory will be passed all available context, including DOM context, with which you can decide how to create a custom symbol for your variable. See "how-to TODO: link me" for more details.

#### Loadbundle example

Below is the meta-data markup for the built-in core loadBundle variable contributor meta-data:

        <cm-element name="loadBundle">

            <cm-attribute name="var">

                <property name="contributes-value-binding">

                    <value>true</value>

                </property>

                <property name="value-binding-scope">

                    <value>request</value>

                </property>

                <property name="value-binding-symbol-factory">

                    <value>org.eclipse.jst.jsf.designtime.core.loadBundle</value>

                </property>

            </cm-attribute>

        </cm-element>

This fragment defines meta-data for the attribute 'var' of tag element 'loadBundle' (the uri for the tag library is declared in the extension point). The meta-data tells the processor to add a variable with scope 'request' using the factory defined by the extension factory id 'org.eclipse.jst.jsf.designtime.core.loadBundle'.
See TODO:link me for more information on how to contribute meta-data for a JSF tag library.

##