|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
---|---|
Mapping | Configuration element describing the mapping between a view identifier URL pattern to a corresponding processor class. |
Mappings | Configuration object used to manage the Mapping instances for
a particular web application. |
Processor | Interface describing business logic responsible for processing an incoming remoting request, and creating the corresponding response. |
Class Summary | |
---|---|
Constants | Manifest constants related to Shale Remoting support. |
Mechanism | Typesafe enumeration of the legal values that may be specified for the
mechanism property of a Mapping . |
XhtmlHelper | Helper bean for rendering links to download resources commonly used in HTML and XHTML pages. |
This package contains interfaces and APIs to support access for remoting
(client side components that need to perform server side activities and/or
retrieve information on a background thread). A JavaServer Faces
PhaseListener
is used to gain control at the end of the
Restore View phase of the request processing lifecycle, and
determine whether or not the view identifier of the requested
view now matches one of a set of configured patterns. When a match is
detected, control of this request is handed over to a configured
Processor instance, which can take complete
responsibility for creating the response for this request (and then
calling FacesContext.responseComplete()
to tell JSF this has been
done). In addition, Processor instances can be
configured to limit the set of resource identifiers which they provide access
to, by pattern matching against "include" and "exclude" pattern lists.
You can define your own Processor implementations, and map them to requests as shown below. Alternatively, the following concrete implementations are available out of the box for your use:
/WEB-INF/lib
directory, without requiring the developer to
modify their build script to extract the resources into the webapp root
directory or a specially configured subdirectory.Chain
or Command
from an appropriate
Catalog
.The static resource serving Processor implentations share the following features:
/WEB-INF
or /META-INF
, Java class
files, and JSP source files).<mime-type>
element in the
web application deployment descriptor), and then by consulting a
fallback list of mappings for common types of resources.If-Modified-Since
HTTP header,
and returning an HTTP "not modified" (304) response if this application
has not been restarted since the resource was served to this client.The dynamic logic invoked by MethodBindingProcessor can use any technique it desires to create the content for this response. Available options (starting with the one that is recommended best practice) include:
ResponseWriter
instance
and use its methods, just as a Renderer
would:
FacesContext context = FacesContext.getCurrentInstance(); ResponseWriter writer = (new ResponseFactory()).getResponseWriter(context, "text/xml"); writer.startDocument(); ... writer.endDocument(); writer.close();
ResponseStream
instance
and use its methods:
FacesContext context = FacesContext.getCurrentInstance(); ResponseStream stream = (new ResponseFactory()).getResponseStream(context, "image/gif"); stream.write(...); ... stream.close();
FacesContext context = FacesContext.getCurrentInstance(); context.getExternalContext().dispatch("/results.jsp");
Before returning, the dynamic logic should call responseComplete()
on the FacesContext
instance for the current request, to bypass
the remaining phases of the JavaServer Faces request processing lifecycle.
In order for a request URI to be processed at all by the Shale remoting
facilities, it must match the mapping for FacesServlet
that is
already defined in /WEB-INF/web.xml
. Once that occurs, JSF will
have constructed a corresponding view identifier that can be retrieved by
calling:
String viewId = FacesContext.getCurrentInstance().getViewRoot().getViewId();
This view identifier is then compared to a set of matching patterns which,
like servlet mappings, can be either prefix matched (/foo/*
) or
extension matched (*.foo
). If the view identifier matches, it will
be transformed into a corresponding resource identifier that is passed
to the process()
method of an appropriate
Processor instance.
Mapping of view identifiers to resources is configured by specifying comma
delimited lists of "pattern:classname" pairs for the following context initialization
parameters in /WEB-INF/web.xml
. For each of these parameters that
is not specified, the value illustrated here will be the default (WARNING
- this decision may be changed later, so double check the latest documentation):
<context-param> <param-name> org.apache.shale.remoting.CLASS_RESOURCES </param-name> <param-value> /static/*:org.apache.shale.remoting.impl.ClassResourceProcessor </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.DYNAMIC_RESOURCES </param-name> <param-value> /dynamic/*:org.apache.shale.remoting.impl.MethodBindingProcessor </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.WEBAPP_RESOURCES </param-name> <param-value> /webapp/*:org.apache.shale.remoting.impl.WebResourceProcessor </param-value> </context-param>
Conditional access controls for a specific Processor implementation are described by configuring comma-delimited lists of patterns (either "/foo/*" style or "*.foo" style) that are matched against the resource id part of the request URL. The standard algorithm applied by the provided implementations (via base class FilteringProcessor) works as follows:
Unless explicitly configured differently, the context init parameters shown below contain default values that will be used for include and exclude patterns:
<context-param> <param-name> org.apache.shale.remoting.CLASS_RESOURCES_EXCLUDES </param-name> <param-value> *.class,*.jsp,*.properties </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.CLASS_RESOURCES_INCLUDES </param-name> <param-value> *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.DYNAMIC_RESOURCES_EXCLUDES </param-name> <param-value> /application/*,/applicationScope/*,/facesContext/*,/request/*,/requestScope/*,/session/*,/sessionScope/*,/view/* </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.DYNAMIC_RESOURCES_INCLUDES </param-name> <param-value> </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.DYNAMIC_RESOURCES_EXCLUDES </param-name> <param-value> </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.DYNAMIC_RESOURCES_INCLUDES </param-name> <param-value> </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.OTHER_RESOURCES_EXCLUDES </param-name> <param-value> *.class,*.jsp,*.properties </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.OTHER_RESOURCES_INCLUDES </param-name> <param-value> *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.WEBAPP_RESOURCES_EXCLUDES </param-name> <param-value> *.class,*.jsp,*.properties </param-value> </context-param> <context-param> <param-name> org.apache.shale.remoting.WEBAPP_RESOURCES_INCLUDES </param-name> <param-value> *.css,*.gif,*.html,*.jpg,*.js,*.png,*.xml </param-value> </context-param>
SECURITY NOTE - Note that, by default, no conditional
restrictions are placed on the managed bean names and public zero-argument
method names referenced by the method binding processor. You will generally
want to restrict access to methods only on those managed beans explicitly
designed to retrieve such callbacks. So, if your application has managed beans
"foo" and "bar" that should allow access, you might set the DYNAMIC_RESOURCES_INCLUDES
parameter to /foo/*,/bar/*
to enforce these restrictions.
In addition, you can configure the following additional context initialization parameters:
org.apache.shale.remoting.OTHER_RESOURCES
- configuration
pairs as described above, which will be marked with the "other"
mechanism type. No default value.org.apache.shale.remoting.MAPPING_CLASS
- fully qualified
classname of class used to create Mapping
instances to record configuration information. If not specified, the
MappingImpl class will be used.org.apache.shale.remoting.MAPPINGS_CLASS
- fully qualified
classname of class used to create a Mappings
instance to record configuration information. If not specified, the
MappingsImpl class will be used.Once the configuration information has been processed (which will occur on
the first JSF request after the application has started), an instance of
Mappings will be stored as an application scope
parameter under the key identified by Globals.MAPPINGS_ATTR
which
contains all of the configuration information being used. This instance might
be useful, for example, to a JSF component that wishes to dynamically determine
the appropriate mapping for class resources.
Given the default resource mappings described above, and assuming that the
developer has mapped FacesServlet
to the *.faces
pattern, the following request URLs will be mapped to appropriate resources
and processed as follows:
http://localhost:8080/myapp/dynamic/foo/bar.faces
Constructs a method binding expression#{foo.bar}
and then executes it. This will cause the bean instance at attribute namefoo
to be located (or created, if necessary), and then the publicbar()
method, which takes no parameters, will be called on that instance.
http://localhost:8080/myapp/static/mycompany/mypackage/MyScript.js.faces
Locates and serves a static resource (/mycompany/mypackage/MyScript.js
) from the web application class loader, which will therefore locate such resources in the/WEB-INF/classes
directory, or packaged in a JAR file in the/WEB-INF/lib
directory.
http://localhost:8080/myapp/webapp/resources/MyScript.js.faces
Locates and serves a static resource (/resources/MyScript.js
)
from the document root of the web application.
|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |