Developer Guide; patch for Cam.
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 4528c57..821164d 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
@@ -1,27 +1,102 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<title>Contributing EL Variables</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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><title>Contributing EL Variables</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="" cellspacing="0" cellpadding="0" width="100%"> -<tr valign="bottom"> +<table summary="" cellpadding="0" cellspacing="0" width="100%"> +<tbody><tr valign="bottom"> <td align="left" width="86%"> <h1>Contributing EL Variables</h1> </td> </tr> -</table> -<hr/> +</tbody></table> +<hr> +<h3>Overview</h3> +The JSF tooling provides three ways to contribute EL variables to the framework depending on the goal of the contribution.<br> +<br> +If you are a component developer and want to add support for EL +variables that are declared by your component tags, you can use the +symbol factory extension and meta-data.<br> +<br> +If you are a tooling developer and you wish to add new sources of +variables without changing the behaviour of other sources (beans, tag +contributed variables), then you can use the symbolProvider extension.<br> +<br> +If you are a tooling developer and you wish to modify the way all +variables are resolved, you can use the variableResolver extension.<br> +<h3>Symbol Factory Extension and Meta-data<br> +</h3> +A symbol factory is any factory class that extends +org.eclipse.jst.jsf.context.symbol.internal.provisional.source.AbstractContextSymbolFactory. +Once you create your implementation, you can declare it to the +framework using the +org.eclipse.jst.jsf.context.symbol.contextSymbolFactory extension +point. In the extension, you need to provide a unique +factoryId. This factoryId is used to identify your factory and +can then be used in your symbol factory meta-data TODO: link to +designtimeappmanager section.<br> +<br> +Your factory implementation will implement the following method:<br> +<br> + protected abstract ISymbol internalCreate(String symbolName, int scope, IAdaptable context, List problems);<br> +<br> +The symbolName 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 IAdapable context +object provides context information about the source of the variable +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 +be able to add diagnostic objects to the list that report warnings or +errors related to symbol creation. Currently, the list is ignored.<br> +<h3>SymbolProvider Extension</h3> +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 +org.eclipse.jst.jsf.context.symbol.symbolSourceProvider +extension. Your symbol provider will implement the +org.eclipse.jst.jsf.context.symbol.internal.provisional.source.ISymbolSourceProviderFactory +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> +- the default variable resolver has been replaced by one that does not call the default external context.<br> +- the default external context has been replaced by one that does not call query the symbol providers.<br> +<br> +<h3>VariableResolver Extension<br> +</h3> +The variable provider extension allows you to register your own design +time resolver. You declare your resolver using the +org.eclipse.jst.jsf.designtime.variableresolver extension point. +Your extension will declare a unique id and a class. The class +must extend +org.eclipse.jst.jsf.designtime.internal.provisional.el.AbstractDTVariableResolver. +To register your resolver as the active one for a project (note: JSF +1.1 only supports a single variable resolver at a given time. +Future versions supporting JSF 1.2 will have a more robust scheme +matching what is defined in the newer specification), you use +DesignTimeApplicationManager.setVariableResolverProvider specifying the +id defined in your extension as the argument.<br> +<br> +Once your variable resolver is registered and active for a project, all +variable resolution requests to the framework will query your +implementation. This gives you complete control over how all EL +variable symbols are discovered and instantiated by the design time +framework.<br> + <p> - CONTENT + <span style="font-style: italic;">Complete information will be available in a future build.</span> </p> -<p> - <span style="font-style:italic">Complete information will be available in a future build.</span> -</p> -</body> -</html> +</body></html>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/jsf_expression_language_tooling.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/jsf_expression_language_tooling.html index a9455d5..46d9499 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/jsf_expression_language_tooling.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/jsf_expression_language_tooling.html
@@ -1,27 +1,337 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<title>JSF Expression Language Tooling</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"/> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head> + <title>JSF Expression Language Tooling</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="" cellspacing="0" cellpadding="0" width="100%"> -<tr valign="bottom"> +<table summary="" cellpadding="0" cellspacing="0" width="100%"> + + +<tbody><tr valign="bottom"> <td align="left" width="86%"> <h1>JSF Expression Language Tooling</h1> </td> </tr> +</tbody> </table> -<hr/> -<p> - This section provides developer information regarding JSF Expression Language Tooling. + + +<hr> +<h3>Overview</h3> + + +<p>The JSF Expression Language (JSF EL) tooling provides basic support +for design time evaluation of JSF 1.1 EL. It implements parts of +the following specifications:</p> + + + + +<a href="http://java.sun.com/javaee/javaserverfaces/download.html">JSF 1.1 Specification</a> -- particularly chapters 5 and 9.<br> + + +<p><a href="http://jcp.org/aboutJava/communityprocess/final/jsr152/">JSP 2.0 Specification</a> -- particularly chapter 2.<br> </p> -<p> - <span style="font-style:italic">Complete information will be available in a future build.</span> -</p> -</body> -</html> + + +In order to support design time evaluation of expressions, the tooling has the following basic capabilities:<br> +<br> +<ul> + <li>syntax parsing <br> + </li> + <li>design-time variable, property and method resolution</li> + <li>semantic type analysis</li> + <li>static expression evaluation</li> +</ul> +<h3>Syntax Parsing<br> +</h3> +The WTP JSP tooling provides an EL parser that the JSF EL tooling +leverage because of syntactic commonality between JSP and JSF EL. +The parser is based on JavaCC and constructs an abstract syntax tree +(AST) that can be further processed by the framework. The parser +reports syntax errors in expressions.<br> +<h3>Design-time variable, property and method resolution</h3> +JSF EL expressions may contain variable and method bindings that +reference external objects. At runtime, this is accomplished +through a several mechanisms, which can convert different types of +identifier symbols into objects and methods. At designtime the +JSF tooling tries to parallel these as closely as possible. These +mechanisms are:<br> +<br> +<ul> + <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 +VariableResolver to return a matching runtime object. At design +time, we parallel this exactly but running 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.<br> +<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> +<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.<br> +<br> +<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span> +<h3>Semantic type analysis</h3> +Type analysis of literals is performed for all expressions. +Analysis is done on all variables, properties and methods that can be +resolved. Type analysis can verify:<br> +<br> +<ul> + <li>that operator arguments are of a valid type or can be coerced to one.</li> + <li>that EL attribute values resolve to a type that is expected by its tag attribute</li> + <li>that the result of an EL expression supports that assignment properties expected by its tag attribute <br> + </li> +</ul> +<h4>Argument Coercability</h4> +Many EL operators expect arguments with a particular type. For +example, the arithmetic addition operator, '+', expects that both of +its operands are numeric. EL does provide for automatic type +coercions and conversions, however some operands cannot be coerced and +will cause runtime errors. The following are examples of +syntactically valid EL expressions that will cause type coercions +exceptions at runtime:<br> +<br> +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;">Expression<br> + </td> + <td style="vertical-align: top;">Problem<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">myBean.stringArrayProperty + myBean.booleanProperty<br> + </td> + <td style="vertical-align: top;">The first operand is an array of strings. Arrays cannot be coerced to a numeric type supported by the addition operator<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">-false<br> + </td> + <td style="vertical-align: top;">Boolean 'false' cannot be coerced to a numeric type expected by the unary minus operator.<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> !5<br> + </td> + <td style="vertical-align: top;">The numeric value '5' cannot be +coerced to a boolean required by the unary not operator (Note this is +what the specification says; some implementation use a C-style +number-to-boolean coercion and flag a warning).<br> + </td> + </tr> + </tbody> +</table> +<br> +<h4>Attribute value compatability</h4> +For those tag attributes that are annotated with JSF tooling meta-data +providing type information, EL type information can be compared to what +is expected by the attribute. Below are some examples of +attribute values being assigned EL expressions that have incompatible +types. The tag prefixes "f" and "h" represent the built-in JSF +"core" and "html" tag libraries respectively.<br> +<br> +<table style="text-align: left; width: 1241px; height: 59px;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top; text-align: center;">Example<br> + </td> + <td style="vertical-align: top; text-align: center;">Problem<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><h:inputText rendered="#{myBean.arrayProperty}"/><br> + </td> + <td style="vertical-align: top;">The rendered attribute expects a boolean value. An array value can be coerced or converted to boolean<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">TODO: more examples<br> + </td> + <td style="vertical-align: top;"><br> + </td> + </tr> + </tbody> +</table> +<br> +<h4>Assignability analysis</h4> +Some JSF tag attributes support the writing back of data to an identified object, such as a bean property:<br> +<br> +e.g. <h:inputText value=#{bean.readOnlyProperty}/><br> +<br> +For tags that are annotated with JSF tooling meta-data, the framework +can check if the property is writable if expected. In the example +above, the inputText will write back the value entered by the user to +bean.readOnlyProperty. However, if the bean doesn't implement a +setter for this property, the user will be issued a warning that the +tag logic may not work completely as expected.<br> +<h3>Static Expression Evaluation</h3> + +The JSF EL validation component performs design time expression +evaluation on an AST provided by the parser. The expression evaluator +is able to do the following expression evaluations:<br> + +<br> + +<ul> +<li>constant expression detection</li><li>logical short-circuit analysis</li><li>possible division by zero<br> + </li> +</ul> + +<h4>Constant expression detection</h4> + +Certain types of expressions can be statically analyzed for +deterministic evaluation. Such deterministic evaluation may imply +programmer error. For example the following expressions always +evaluate to a constant value regardless of runtime conditions:<br> + +<br> + +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> + + <tbody> + <tr> + <td style="vertical-align: top; text-align: center;">Expression<br> + </td> + <td style="vertical-align: top; text-align: center;">Constant Evaluation<br> + </td> + <td style="vertical-align: top; text-align: center;">Reason<br> + </td> + </tr> + <tr> + <td style="vertical-align: top; text-align: center;">5+3<br> + </td> + <td style="vertical-align: top; text-align: center;">8<br> + </td> + <td style="vertical-align: top;">All values in the expression are constant at design time.<br> + </td> + </tr> + <tr> + <td style="vertical-align: top; text-align: center;">empty 'notEmpty'<br> + </td> + <td style="vertical-align: top; text-align: center;">false<br> + </td> + <td style="vertical-align: top;">Empty operator always returns false for non-null, non-empty strings<br> + </td> + </tr> + <tr> + <td style="vertical-align: top; text-align: center;">empty 5<br> + </td> + <td style="vertical-align: top; text-align: center;">false<br> + </td> + <td style="vertical-align: top;">The empty operator always returns false if the argument is not a string, collection, array or map<br> + </td> + </tr> + <tr> + <td style="vertical-align: top; text-align: center;">-null<br> + </td> + <td style="vertical-align: top; text-align: center;">0<br> + </td> + <td style="vertical-align: top;">The minus operator treats null as 0.<br> + </td> + </tr> + </tbody> +</table> + +<br> + +<h4>Logical short-circuit analysis<br> +</h4> + +JSF EL supports short-circuit evaluation of boolean expressions. This +cause entire sub-expressions to not be evaluated and those important +side-effects may not occur. The following are examples of EL +expressions that will be short-circuited:<br> + +<br> + +<table style="text-align: left; height: 80px; width: 1241px;" border="1" cellpadding="2" cellspacing="2"> + + <tbody> + <tr> + <td style="vertical-align: top;">Expression<br> + </td> + <td style="vertical-align: top;">Description<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">false && myBean.x<br> + </td> + <td style="vertical-align: top;">This logical predicate always +evaluates to false regardless of the value of myBean.x. Because this +expression "short-circuits" on the first argument, myBean.x will never +be evaluated meaning any expected side-effects will not occur.<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">true || myBean.x<br> + </td> + <td style="vertical-align: top;">Similar to the above, myBean.x will never be evaluated because true or'd with any value is guaranteed to be true.<br> + </td> + </tr> + </tbody> +</table> + +<br> + +<h4>Possible division by zero</h4> + +Division by zero can cause runtime exceptions in a JSF application. +The following are examples of EL expressions that may result in a +divide-by-zero error:<br> + +<br> + +'x / 0'<br> + +'x / (5-5)'<br> +<br> + + + + + +</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 f7bbd26..c831888 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
@@ -1,27 +1,132 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><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="" cellspacing="0" cellpadding="0" width="100%"> -<tr valign="bottom"> +<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> +<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 behaviours 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 +designtime, 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 TODO<br> +<h3>Pluggable resolvers</h3> +TODO<br> +<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> -<hr/> -<p> - CONTENT -</p> -<p> - <span style="font-style:italic">Complete information will be available in a future build.</span> -</p> -</body> -</html> +<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>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/using_context_resolvers.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/using_context_resolvers.html index c0ceb08..6e7c5dd 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/using_context_resolvers.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/using_context_resolvers.html
@@ -1,27 +1,145 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<title>Using Context Resolvers</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"/> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head> + <title>Using Context Resolvers</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="" cellspacing="0" cellpadding="0" width="100%"> -<tr valign="bottom"> +<table summary="" cellpadding="0" cellspacing="0" width="100%"> + +<tbody><tr valign="bottom"> <td align="left" width="86%"> <h1>Using Context Resolvers</h1> </td> </tr> +</tbody> </table> -<hr/> -<p> - CONTENT -</p> -<p> - <span style="font-style:italic">Complete information will be available in a future build.</span> -</p> -</body> -</html> + +<hr> +<h3>Overview</h3> + +Context resolvers are an abstraction used by the JSF EL framework to +decouple sources of context information from the way that information +is created. Common examples of such contexts are:<br> + +<br> + +- a dynamic web project in an Eclipse workspace<br> + +- a JSP file in a dynamic web project<br> + +- a particular absolute offset into an IDocument<br> + +<br> + +Context resolvers allow us to derive interesting information from these contexts such as:<br> + +<br> + +- what is the current IProject?<br> + +- where are we in an IRegion or DOM tree?<br> + +- what JSF EL symbols are available at the current IDocument position?<br> + +<br> + +<h3>IStructuredDocumentContext</h3> + +A particularly useful context is one in an IStructuredDocument. +An IStructuredDocument represents an SSE document that can be +manipulated in a number of different ways including as a regular +IDocument or as a DOM. The IStructuredDocumentContext points to a +specific absolute offset into such a document. The context can +then be passed to various resolvers to determine information about this +position in the document.<br> + +<br> + +<h3>Context Resolvers</h3> + +<br> + +The following is a list of context resolvers that are available as provisional APIs:<br> + +<br> + +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> + + <tbody> + <tr> + <td style="vertical-align: top;">Resolver Type<br> + </td> + <td style="vertical-align: top;">Purpose<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">ITaglibContextResolver</td> + <td style="vertical-align: top;">Resolves taglib information for the current context such + as retrieving the tag library information for the current tag.</td> + </tr> + <tr> + <td style="vertical-align: top;">IWorkspaceContextResolver</td> + <td style="vertical-align: top;">Resolves workspace information for the current document + context such as IFile and IProject.</td> + </tr> + <tr> + <td style="vertical-align: top;">IDOMContextResolver</td> + <td style="vertical-align: top;">Resolves DOM information for the current context such as + current element and attribute.</td> + </tr> + <tr> + <td style="vertical-align: top;">IMetadataContextResolver</td> + <td style="vertical-align: top;">Resolves meta-data framework information for a given + context.<span style=""> </span>For example, if the current + context resolves to an XML attribute, retrieves meta-data associate with that + attribute/element/uri.</td> + </tr> + <tr> + <td style="vertical-align: top;">ISymbolContextResolver</td> + <td style="vertical-align: top;">Determines what symbols are available or valid within the + current context.<span style=""> </span>For example, if + context is an EL expression, what bean names are available?</td> + </tr> + </tbody> +</table> + +<br> +<h3>Factories</h3> +Factories exist to create both contexts and context resolvers. These are:<br> +<br> +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;">Factory Name<br> + </td> + <td style="vertical-align: top;">What it does<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">org.eclipse.jst.jsf.context.structureddocument.internal.provisional.IStructuredDocumentContextFactory<br> + </td> + <td style="vertical-align: top;">Creates new IStructuredDocumentContext objects based on a document and offset.<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;">org.eclipse.jst.jsf.context.resolver.structureddocument.internal.provisional.IStructuredDocumentContextResolverFactory<br> + </td> + <td style="vertical-align: top;">Creates a new instances of context resolvers for an IStructuredDocumentContext.<br> + </td> + </tr> + </tbody> +</table> +<br> +<h3>Adding Factory Delegates</h3> +TODO:<br> + +</body></html>