Zaphod – betterFORM As Service (Cross Context Environment)
This article describes how to use betterFORM from within a different servlet container context. It allows to store or generate forms in your application context and let betterFORM process the form in its own context.
- Easy and independently updating the software in the separated contexts.
- Usage of the same software library in different versions. Since both software stacks are loaded from different class loaders the do not interfere each other.
- Creating XForms from within your web application. The created form is processed in the context of betterFORM.
- more complex configuration
- The setup can only be used in one servlet container. Both contexts have to be deployed on the same servlet container. Distributed systems are not supported at the moment.
- The servlet container must allow to access the context of betterFORM. Most servlet container allow this by default. Apache needs to be configured separately. The current distributions of betterFORM already contains a context.xml file which allows other contexts to access the context of betterFORM.
- The distributed filter class muss be installed in the context which accesses betterFORM. An Jar file is (not yet) distributed.
- The filter must me configured correctly. The filter is configured in the deployment descriptor of the web application.
All the configuration is done in the deployment descriptor. betterFORM itself is already configured for this configuration. In the deployment descriptor one has to specify:
- the URL for the filter.
- the context name of betterFORM.
- and URL which points back to the applications context
The filter is mapped to an URL pattern. If a request matches the pattern the returned page is send to betterFORM and processed as an XForm form. Under the URL one can store forms in files or servlets which generate forms.
The name of the betterFORM context is configured through the filter parameter xforms.engine.webcontext. It should contain the name of the context as string (defaults to ‘betterform’).
In the filter parameter
xforms.engine.resource one must specifies an URL which points back to the filter. The url has to be appended with an virtual directory. This allows the filter to handle and forward requests which are resources within the betterFORM context. This applies to css, scripts and images distributed with betterFORM.
Additionally one can configure the servlet which processes forms in betterFORM. It is not recommended to change this variable. It is intended for development.
Examples for Apache Tomcat
The following example files should work with Tomcat 5.5.x and Tomcat 6.x.
This file is only needed when betterFORM is used together with Tomcat. It should be stored in the directory META-INF under the name context.xml. When first deployed Tomcat copies it to its own directory structure. Changes after the first deployment are not considered.
<?xml version="1.0" encoding="UTF-8"?> <Context antiJARLocking="true" crossContext="true" path="/betterform"/>
This file shows a minimal setup. The setup renders all forms in the
forms directory with the help of betterFORM into an html page. The setup specifies the context in which betterFORM is running. Its important that the path of
xforms.engine.resources is set to the same directory as the patter of the filter.
<?xml version="1.0" encoding="UTF-8"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <description>..</description> <display-name>Sample Application</display-name> <filter> <filter-name>CrossContextFilter</filter-name> <filter-class>de.betterform.agent.web.filter.CrossContextFilter</filter-class> <init-param> <param-name>xforms.engine.webcontext</param-name> <param-value>betterform</param-value> </init-param> <init-param> <param-name>xforms.engine.servlet</param-name> <param-value>/repeater</param-value> </init-param> <init-param> <param-name>xforms.engine.resources</param-name> <param-value>/SampleApp/forms/forward</param-value> </init-param> </filter> <filter-mapping> <filter-name>CrossContextFilter</filter-name> <url-pattern>/forms/*</url-pattern> </filter-mapping> </web-app>
The current status of this configuration is experimental. We have not yet used this setup with any of our clients. This is the first public release. So be warned!
In the current version the code should allow authentication. It does not support the configuration of betterFORM with absolute URLs.
The configuration of the filter in the WEB.xml is quite complex and error prone. I would be much better to generate the path to betterFORMs internal resources.