Package org.apache.shale.remoting

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).

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.
 

Package org.apache.shale.remoting Description

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:

The static resource serving Processor implentations share the following features:

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:

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:

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:

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.



Copyright © 2004-2007 Apache Software Foundation. All Rights Reserved.