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 821164d..8175233 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
@@ -5,26 +5,26 @@
<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>Contributing EL Variables</h1>
+ <h1>Contributing EL Variables</h1>
+
</td>
</tr>
</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>
+The JSF tooling provides three ways to contribute EL variables to the framework depending on your goal.<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>
+variables without changing the behavior of other sources (beans, tag
+contributed variables), 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>
@@ -37,8 +37,7 @@
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>
+can then be used in your symbol factory meta-data section. See also the <a href="the_design_time_application_manager.html">Design Time Application Manager</a> for information.<br>
<br>
Your factory implementation will implement the following method:<br>
<br>
@@ -50,7 +49,7 @@
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
+obligated to use this scope variable. The IAdaptable 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
@@ -73,7 +72,7 @@
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>
+- the default external context has been replaced by one that does not query the symbol providers.<br>
<br>
<h3>VariableResolver Extension<br>
</h3>
@@ -91,12 +90,9 @@
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
+variable resolution requests to the framework will call your
implementation. This gives you complete control over how all EL
variable symbols are discovered and instantiated by the design time
framework.<br>
-<p>
- <span style="font-style: italic;">Complete information will be available in a future build.</span>
-</p>
</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 46d9499..8a210d3 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,6 +1,6 @@
<!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>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><title>JSF Expression Language Tooling</title>
+
@@ -18,9 +18,7 @@
- <link rel="stylesheet" href="../../book.css" type="text/css">
-</head>
-
+ <link rel="stylesheet" href="../../book.css" type="text/css"></head>
<body>
<table summary="" cellpadding="0" cellspacing="0" width="100%">
@@ -52,8 +50,7 @@
</p>
-In order to support design time evaluation of expressions, the tooling has the following basic capabilities:<br>
-<br>
+In order to support design-time evaluation of expressions, the tooling has the following basic capabilities:<br>
<ul>
<li>syntax parsing <br>
</li>
@@ -64,15 +61,15 @@
<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.
+leverage because of the 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
+(AST) that is 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
+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>
<br>
@@ -80,49 +77,16 @@
<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>
+</ul>For more information on pluggable resolvers, see <a href="the_design_time_application_manager.html">The Design Time Application Manager</a>.<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>
+resolved. Type analysis can verify that:<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>operator arguments are of a valid type or can be coerced to one.</li>
+ <li>EL attribute values resolve to a type that is expected by its tag attribute</li>
+ <li>the result of an EL expression supports the assignment properties expected by its tag attribute <br>
</li>
</ul>
<h4>Argument Coercability</h4>
@@ -166,13 +130,12 @@
</tbody>
</table>
<br>
-<h4>Attribute value compatability</h4>
+<h4>Attribute value compatibility</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>
+types. The tag prefix "h" represents the built-in JSF "html" tag library.<br>
<br>
<table style="text-align: left; width: 1241px; height: 59px;" border="1" cellpadding="2" cellspacing="2">
<tbody>
@@ -189,9 +152,11 @@
</td>
</tr>
<tr>
- <td style="vertical-align: top;">TODO: more examples<br>
+ <td style="vertical-align: top;"><h:dataTable binding="#{myBeanSubClass.booleanProperty}"/><br>
</td>
- <td style="vertical-align: top;"><br>
+ <td style="vertical-align: top;">The
+binding attribute expects a binding to a UIComponent object. The
+boolean property can be neither converted or coerced to a valid type.<br>
</td>
</tr>
</tbody>
@@ -203,7 +168,7 @@
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
+can check if the property is writable as 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
@@ -254,7 +219,7 @@
</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 style="vertical-align: top;">Empty operator always returns false for non-null, non-empty strings.<br>
</td>
</tr>
<tr>
@@ -262,7 +227,7 @@
</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 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>
@@ -280,9 +245,9 @@
<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
+JSF EL supports short-circuit evaluation of boolean expressions.
+Short-circuit evaluation can cause entire sub-expressions to not be
+evaluated and important
side-effects may not occur. The following are examples of EL
expressions that will be short-circuited:<br>
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 c831888..607cbd2 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
@@ -5,7 +5,6 @@
<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">
@@ -25,10 +24,9 @@
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>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>
@@ -36,15 +34,68 @@
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>
+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 TODO<br>
+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>
-TODO<br>
+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
@@ -70,12 +121,15 @@
</td>
<td style="vertical-align: top;">true or false<br>
</td>
- <td style="vertical-align: top;">This property alerts the model
+ <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>
+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>
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 6e7c5dd..c930759 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,6 +1,6 @@
<!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>
+<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">
@@ -9,9 +9,7 @@
<meta http-equiv="Content-Script-Type" content="text/javascript">
- <link rel="stylesheet" href="../../book.css" type="text/css">
-</head>
-
+ <link rel="stylesheet" href="../../book.css" type="text/css"></head>
<body>
<table summary="" cellpadding="0" cellspacing="0" width="100%">
@@ -139,7 +137,18 @@
</tbody>
</table>
<br>
-<h3>Adding Factory Delegates</h3>
-TODO:<br>
+<h3>Adding Factory Delegates</h3>The existing factories can be extended
+using factory delegates. A delegate for
+IStructuredDocumentContextFactory allows you to extend the existing
+factory to create IStructuredDocumentContext's for document contexts
+other than an IStructuredDocumentContext and offset. Similarly,
+adding factory delegates to IStructuredDocumentContextResolverFactory
+allows you to create context resolvers for structured documents other
+than those already supported.<br>
+<br>
+Factory delegates are added programmatically be calling
+addFactoryDelegate on the appropriate factory. See the JavaDoc
+for IDelegatingFactory for more details.<br>
+
</body></html>
