Fix for PMC approved bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=232206. Updates design docs and fixes minor lazy load warning on Manifest.mf.
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/build.properties b/plugins/org.eclipse.jst.jsf.doc.dev/build.properties index 3041c27..b5fc44e 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/build.properties +++ b/plugins/org.eclipse.jst.jsf.doc.dev/build.properties
@@ -10,7 +10,6 @@ ############################################################################### bin.includes = META-INF/,\ plugin.xml,\ - bookOLD.css,\ html/,\ plugin.properties,\ toc.xml,\
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/contributing_el_variables.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/contributing_el_variables.html index a72bb2f..949b644 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/contributing_el_variables.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/contributing_el_variables.html
@@ -43,24 +43,40 @@ <br> Your factory implementation will implement the following method:<br> <div class="code"><pre> -protected abstract ISymbol internalCreate(String symbolName, int scope, IAdaptable context, List problems);<br> +protected abstract ISymbol internalCreate(String symbolName, int scope, IAdaptable context, List problems, final IAdditionalContextSymbolInfo additionalInfo); </pre></div> -The symbolName is the one provided by the system, usually corresponding -to the tag attribute, that declares the variable. You may use +<br>The <i>symbolName</i> is the one provided by the system, usually corresponding +to the tag attribute, that declares the variable. You may use this symbol name or ignore it and use your own, depending on how the -variable will be named at runtime. The scope argument is one of -ISymbolConstants.SYMBOL_SCOPE_*. The system value is passed in -based on meta-data settings if present. Your factory is not -obligated to use this scope variable. The IAdaptable context +variable will be named at runtime. The <i>scope</i> argument is one of +ISymbolConstants.SYMBOL_SCOPE_*. The system value is passed in +based on meta-data settings if present. Your factory is not +obligated to use this scope variable. The IAdaptable <i>context</i> object provides context information about the source of the variable -declaration. This is usually an IModelContext object. You +declaration. This is usually an IModelContext object. You can implement the supports() abstract method in such a way to tell the -framework work what types of context object you support. -The problems list is for future use. In future versions, you will +framework what types of context object you support. +The <i>problems</i> list is for future use. In future versions, you will be able to add diagnostic objects to the list that report warnings or -errors related to symbol creation. Currently, the list is ignored.<br> +errors related to symbol creation. Currently, the list is ignored. The additionalInfo interface (if non-null) contains optional information provided to the framework about how to construct on an object<br> +<h4>Simplified Symbol Context Factories</h4> +<p>Starting in WTP 3.0, several default symbol factories have been added for common tasks. +These new factories can be used by specifying their factory ids (see <a href="the_design_time_application_manager.html#jsp_document_processor">JSP model processor</a>). The following are the new ids with an explanation of their function:<br><br></p> + +<table border="1"> +<tr><th>Id</th><th>Additional meta-data</th><th>Explanation</th></tr> +<tr><td>org.eclipse.jst.jsf.core.staticJavaTypeSymbol</td><td>optional-value-binding-static-type</td><td>Creates a statically-typed Java symbol based on the type signature passed using optional-value-binding-static-type meta-data value.</td></tr> +<tr><td>org.eclipse.jst.jsf.core.valueExpressionSymbolFactory</td><td>optional-value-binding-valueexpr-attr</td><td>Creates a new symbol, using the attribute on the current tag specified by optional-value-binding-valueexpr-attr to extract type information from an EL expression.</td></tr> +<tr><td>org.eclipse.jst.jsf.common.unknownTypeSymbolFactory</td><td> </td><td>Creates a new symbol with an unknown type that effectively allows all properties as valid.</td></tr> +</table> + +<br> +<p><b>Deprecation note:</b> Prior to WTP release 3.0 (Ganymede train), the method:</p> +<div class="code"><pre> +protected abstract ISymbol internalCreate(String symbolName, int scope, IAdaptable context, List problems); +</pre></div><p>was used for this API. This method is now deprecated in favor of the new method that takes the IAdditionalContextSymbolInfo object. Existing code is still backward compatible and is the equivalent of calling the new method with <i>null</i> for the additionalInfo argument. You can migrate to the new method by simply implementing it instead and ignoring the additionalInfo argument which is always optional.</p> <h3>SymbolProvider Extension</h3> -JSF has many ways to contribute variables. If the framework has +<p>JSF has many ways to contribute variables. If the framework has overlooked any or if you have added new ways yourself without affecting the way other variables, such as managed beans, are declared, then you can do so through the @@ -69,10 +85,10 @@ <code>org.eclipse.jst.jsf.context.symbol.source.ISymbolSourceProviderFactory</code> interface. Every time the framework requests a list of variables through the default VariableResolver and ExternalContext, your provider -will be queried for all its symbols at one or more scopes.<br> -<br> -Note that your symbol provider may not called if:<br> -<br><ul> +will be queried for all its symbols at one or more scopes.</p> + +<p>Note that your symbol provider may not called if:</p> +<ul> <li>the default variable resolver has been replaced by one that does not call the default external context.</li> <li>the default external context has been replaced by one that does not query the symbol providers.</li> </ul> @@ -96,4 +112,18 @@ variable symbols are discovered and instantiated by the design time framework.</p> +<h4>Decorative resolvers</h4> + +<p>Starting in WTP 3.0, Variable and Property Resolvers support a decorative mechanism for adding +variables and properties. By setting the forRuntimeClass on the extension for these resolvers +you can cause the resolver to only be consulted if the runtime class specified is found in the +application configuration. This allows the design time to behave similar to the runtime which +allows decorative chaining of variable and property resolvers. See +the <a href="../extpts_reference/jsf/org_eclipse_jst_jsf_core_variableresolver.html">org.eclipse.jst.jsf.core.variableresolver extension point.</a> for more information.</p> + +<h4>Per-project resolvers</h4> + +<p>Starting in WTP 3.0, Variable and Property Resolvers can be declared as being constructed on per-project +basis instead of the (default) per-workspace convention. See the entension point docs on instancePerProject value +for more information.</p> </body></html>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/the_design_time_application_manager.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/the_design_time_application_manager.html index 4f97d3d..8a9b187 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/the_design_time_application_manager.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/the_design_time_application_manager.html
@@ -10,30 +10,37 @@ </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> + <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. +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. <p>The DTAppMgr is comprised of the following main components:</p> <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> + <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> +<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 @@ -42,126 +49,148 @@ 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 -<code>org.eclipse.jst.jsf.designtime.context.AbstractDTExternalContextFactory</code>. -To set your external context factory as the current one, use -<code>DesignTimeApplicationManager.setExternalContextProvider(String)</code>. -Note that by changing the current ExternalContextProvider on a project, -you will significantly change the behavior of how variables are +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 +<code>org.eclipse.jst.jsf.designtime.context.AbstractDTExternalContextFactory</code> +. To set your external context factory as the current one, use +<code>DesignTimeApplicationManager.setExternalContextProvider(String)</code> +. Note that by changing the current ExternalContextProvider on a +project, you will significantly change the behavior of how variables are resolved in EL expressions. <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: +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: <ul> -<li>VariableResolver</li><li>PropertyResolver</li><li>MethodBinding -</li> + <li>VariableResolver</li> + <li>PropertyResolver</li> + <li>MethodBinding</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 +<p>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>. +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>.</p> <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> +<p>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".</p> <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 +<p>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</h3> +content assist.</p> +<h3><a id="jsp_document_processor">JSP document processor</a></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 +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: -<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;font-weight: bold">Meta-data Trait<br> - </td> - <td style="vertical-align: top;font-weight: bold">Valid Values<br> - </td> - <td style="vertical-align: top; font-weight: bold">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 '<a href="../extpts_reference/jsf/org_eclipse_jst_jsf_common_contextSymbolFactory.html">org.eclipse.jst.jsf.common.contextSymbolFactory</a>'.<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 <a href="./contributing_el_variables.html">Contributing EL Variables</a> for -more details.<br> - </td> - </tr> - </tbody> +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" + cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top; font-weight: bold">Meta-data + Trait<br> + </td> + <td style="vertical-align: top; font-weight: bold">Valid Values<br> + </td> + <td style="vertical-align: top; font-weight: bold">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 '<a + href="../extpts_reference/jsf/org_eclipse_jst_jsf_common_contextSymbolFactory.html">org.eclipse.jst.jsf.common.contextSymbolFactory</a>'.<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 <a + href="./contributing_el_variables.html">Contributing EL + Variables</a> for more details.<br> + </td> + </tr> + <tr> + <td><p>optional-value-binding-static-type</p> + + <p><b>From 3.0</b></p></td> + <td>Must be of the form "Ljava.lang.String;". See the + JDT Signature class for more information</td> + <td>A java signature that suggests a static type for the + resulting symbol. <b>Optional.</b></td> + </tr> + <tr> + <td><p>optional-value-binding-valueexpr-attr</p><p><b>From 3.0</b></p></td><td>Must be the name of an attribute on the same element.</td><td>The name of the attribute on the same element that will hold a value expression whose type will be used as the type of the resulting symbol. <b>Optional.</b></td> + </tr> + </tbody> </table> <h4>Loadbundle example</h4> -Below is the meta-data markup for the built-in core loadBundle variable contributor meta-data: -<div class="code"> -<pre> +Below is the meta-data markup for the built-in core loadBundle variable +contributor meta-data: +<div class="code"><pre> <entity id="loadBundle"> <entity id="var"> <trait id="contributes-value-binding"> @@ -175,19 +204,24 @@ </trait> </entity> </entity> -</pre> -</div> -<p>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'.</p> +</pre></div> +<p>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'.</p> <h4>Other Information</h4> <ul> -<li><a href="./metadata_framework.html">Design-time Meta-data Framework</a></li> -<li><a href="../tutorials/implementing_a_new_tag_based_el_variable_contributor_for_jsp.html">EL Variable Contributor Tutorial</a></li> -<li><a href="../tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html">Contributing Meta-data for Apache Tomahawk Component Tutorial</a></li> + <li><a href="./metadata_framework.html">Design-time Meta-data + Framework</a></li> + <li><a + href="../tutorials/implementing_a_new_tag_based_el_variable_contributor_for_jsp.html">EL + Variable Contributor Tutorial</a></li> + <li><a + href="../tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html">Contributing + Meta-data for Apache Tomahawk Component Tutorial</a></li> </ul> -</body></html> +</body> +</html>
diff --git a/plugins/org.eclipse.jst.jsf.doc.user/META-INF/MANIFEST.MF b/plugins/org.eclipse.jst.jsf.doc.user/META-INF/MANIFEST.MF index 87b4826..3f63a24 100644 --- a/plugins/org.eclipse.jst.jsf.doc.user/META-INF/MANIFEST.MF +++ b/plugins/org.eclipse.jst.jsf.doc.user/META-INF/MANIFEST.MF
@@ -5,5 +5,5 @@ Bundle-Version: 1.1.0.qualifier Bundle-Localization: plugin Require-Bundle: org.eclipse.help;bundle-version="[3.2.0,4.0.0)" -Eclipse-LazyStart: true +Bundle-ActivationPolicy: lazy Bundle-Vendor: %plugin.provider