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.

Concrete Processor Implementations

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:

• ClassResourceProcessor - Serves static resources (such as stylesheets or JavaScript source files) from the web application classpath. In other words, resource files can be packaged inside a JAR file that is included in the /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.
• WebResourceProcessor - Serves static resources (such as stylesheets or JavaScript source files) from the web application's document root. This is essentially the same as allowing your servlet container's default file-serving servlet to serve the resources, but allows operation in scenarios where such a file serving servlet has not been configured.
• MethodBindingProcessor - Translates the resource portion of the URL (see examples below) into a JavaServer Faces method binding expression that points at a public method taking no parameters, and then executes a call to this method. As a result of evaluating the method binding, it is possible that the JavaServer Faces managed beans facility will be invoked to create and configure the bean containing the called method.
• ChainProcessor - Translates the resource portion of the URL into execution of an appropriate Commons Chain Chain or Command from an appropriate Catalog.

The static resource serving Processor implentations share the following features:

• Unconditionally disallow access to prohibited resources (web application resources under /WEB-INF or /META-INF, Java class files, and JSP source files).
• Conditionally allow or disallow access to other resources based on include and exclude pattern lists.
• Set the content type of the response based on the extension portion of the resource identifier. This is done by first consulting the servlet or portlet container (which supports mapping of extensions to content types with a <mime-type> element in the web application deployment descriptor), and then by consulting a fallback list of mappings for common types of resources.
• Support browser caching of static content, by watching for incoming requests that contain an 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.
• Requests for non-existent resources will return a standard HTTP "not found" (404) response.
• Standard servlet access control features may be applied to the served resources, by using standard security constraint elements in the web application deployment descriptor.

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:

• For a text response, acquire a 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();
          

• For a binary response, acquire a ResponseStream instance and use its methods:

  FacesContext context = FacesContext.getCurrentInstance();
  ResponseStream stream = (new ResponseFactory()).getResponseStream(context, "image/gif");
  stream.write(...);
  ...
  stream.close();
          

• Stash relevant model data (typically in request scope), and then forward to a JSP page (with either JSF components or JSTL tags coupled with EL expressions) that will produce the actual response:

  FacesContext context = FacesContext.getCurrentInstance();
  context.getExternalContext().dispatch("/results.jsp");
          

• Access the response object from the external context, and acquire a writer or stream from the response object directly. Note that this technique, unlike those illustrated above, requires you to program specfically to either the servlet or portlet response APIs.

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.

Configuring Remoting Support

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:

• If there is an "excludes" list for this processor, and the resource id portion of the request URL matches one of these patterns, reject the request by returning an HTTP 404 (not found) status.
• If there is an "includes" list for this processor, and the resource id portion of the request URL matches one of these patterns, perform the processing required to deliver the requested response.
• If there is an "includes" list for this processor, and we reached this point, reject the request by returning an HTTP 404 (not found) status, because the resource URL did not match one of the "include" patterns.
• Because we did not reject the resource id for an "excludes" list match, and there was no "includes" list, perform the processing required to deliver the requested response.

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.

Example URLs

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 name foo to be located (or created, if necessary), and then the public bar() 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.