| <html><head><title>The Design Time Application Manager</title> |
| |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <meta http-equiv="Content-Script-Type" content="text/javascript"> |
| <link rel="stylesheet" href="../../book.css" type="text/css"></head> |
| <body> |
| <table summary="" cellpadding="0" cellspacing="0" width="100%"> |
| <tbody><tr valign="bottom"> |
| <td align="left" width="86%"> |
| <h1>The Design Time Application Manager</h1> |
| </td> |
| </tr> |
| </tbody></table> |
| <hr> |
| <h3>Overview</h3> |
| 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.<br> |
| <br> |
| The DTAppMgr is comprised of the following main components:<br> |
| <ul> |
| <li>a simulated FacesContext, called DTFacesContext, used to simulates part of this key runtime context object.</li> |
| <li>a pluggable ExternalContext, called DTExternalContext to support different behaviors in different containers (i.e. JSP).</li> |
| <li>pluggable resolvers for EL variables, properties and methods including default implementations.</li> |
| <li>a JSP processor that can update simulated design time state based on a JSP page and tag-based meta-data.</li> |
| </ul> |
| <h3><span style="font-weight: bold;">The simulated FacesContext</span></h3> |
| 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.<br> |
| <h3>Pluggable ExternalContext</h3> |
| 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.<br> |
| <h3>Pluggable resolvers</h3> |
| 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:<br> |
| |
| <ul> |
| <li>VariableResolver</li><li>PropertyResolver</li><li>MethodBinding<br> |
| </li> |
| </ul> |
| <h4>VariableResolver</h4> |
| |
| 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 <a href="contributing_el_variables.html">Contributing EL Variables</a>. |
| <h4>PropertyResolver</h4> |
| |
| 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".<br> |
| |
| <h4>MethodBinding</h4> |
| |
| 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. |
| <h3>JSP document processor<br> |
| </h3> |
| 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:<br> |
| <br> |
| <table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;">Meta-data property<br> |
| </td> |
| <td style="vertical-align: top;">Valid Values<br> |
| </td> |
| <td style="vertical-align: top;">Description<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">contributes-value-binding<br> |
| </td> |
| <td style="vertical-align: top;">true or false<br> |
| </td> |
| <td style="vertical-align: top;">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.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">value-binding-scope<br> |
| </td> |
| <td style="vertical-align: top;">'request', 'session', 'application'<br> |
| </td> |
| <td style="vertical-align: top;">This property will set the runtime scope for the contribute variable. The default is 'request' if not provided.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">value-binding-symbol-factory<br> |
| </td> |
| <td style="vertical-align: top;">An corresponding to a 'factoryId' field on a valid extension of 'org.eclipse.jst.jsf.context.symbol.contextSymbolFactory'.<br> |
| </td> |
| <td style="vertical-align: top;">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.<br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <h4>Loadbundle example</h4> |
| Below is the meta-data markup for the built-in core loadBundle variable contributor meta-data:<br> |
| <br> |
| <pre> <cm-element name="loadBundle"></pre> |
| <pre> <cm-attribute name="var"></pre> |
| <pre> <property name="contributes-value-binding"></pre> |
| <pre> <value>true</value></pre> |
| <pre> </property></pre> |
| <pre> <property name="value-binding-scope"></pre> |
| <pre> <value>request</value></pre> |
| <pre> </property></pre> |
| <pre> <property name="value-binding-symbol-factory"></pre> |
| <pre> <value>org.eclipse.jst.jsf.designtime.core.loadBundle</value></pre> |
| <pre> </property></pre> |
| <pre> </cm-attribute></pre> |
| <pre> </cm-element></pre> |
| <br> |
| 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'.<br> |
| <br> |
| See TODO:link me for more information on how to contribute meta-data for a JSF tag library. |
| <h2><span style="font-weight: bold;"></span></h2> |
| |
| |
| </body></html> |
