Integration in a Servlet Container

Libraries

The distribution consists only of libraries that have to be copied in the classpath. A few libraries are only for specific functions, so they are optional. The Java XML-Streaming-API is default since J2EE 5.0 so it has to be included only in older implementations.
Descriptions to this libraries are contained in lib/libraries.txt.

Filter configuration

To include in a servlet three filter are necessary. The URL pattern should be kept as abstract as possible - in best case "/*". So that each request will be pass through each filter if possible. So that the filter could decide with the help of the URL to execute a request. Not relevant requests will be passed to the next filter in the command structure. (Requests for resources (like css files etc.) need to be handled by filters in a dynamic way, even if they are sent to the server with different URL paths. Therefore, the filter mapping must not be configured for a specific (static) path). 

<filter>
  <filter-name>ResourceFilter</filter-name>
  <filter-class>de.imatics.j2ee.filter.ResourceFilter</filter-class>
</filter>

<filter>
  <filter-name>ActionFilter</filter-name>
  <filter-class>de.imatics.j2ee.filter.ActionFilter</filter-class>
  <init-param>
    <param-name>action-mapping</param-name>
    <param-value>FEAction=de.imatics.forms.render.html.ActionHandler</param-value>
  </init-param>
</filter>

<filter>
  <filter-name>SubmissionFilter</filter-name>
  <filter-class>de.imatics.forms.render.html.SubmissionFilter</filter-class>
</filter>


<filter-mapping>
  <filter-name>ResourceFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>ActionFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>SubmissionFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
  • ResourceFilter
    Allocate several default icons that will be used in the default CSS file for the forms.
  • ActionFilter
    Forwards action-request by AJAX to the respective Java method. These include for example specific renderer actions such as adding and removing rows in repeat-tables.
  • SubmissionFilter
    Similar to the ActionFilter actions are executed via AJAX. SubmissionFilter processes specific requests these commit the values of the form to the server.

Form-Servlet

There is a default servlet to display forms, declared by XML definition.
Optional de.imatics.forms.render.html.FormServlet can be activated via the web.xml. This functionality already exists by the included filters if the URL path begins with /form/. If the XML definition of the forms are available as a resource in the class path, the path of the form definition can be passed as a parameter or specified as a path in the URL.

The call
/form/path/to/form
loading the form definition from file form.xml in package path.to.

This call to display forms is necessary to test forms or is used for forms in pop-ups.

Integration in a JSP

*FormEngine generates XHTML code so the HTML page should also declared as XHTML in DOCTYPE. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

First you have to generate an instance from a form definition. Form definitions can be created using the API or the declaration will be loaded from an XML definition. The method loadDefinition receives as parameter the path to a resource file from the classpath and provides internal caching of already loaded form definitions. For multiple uses of a form generated FormDefinition must not be cached. The internal cache takes care for an update, if the XML file is modified, so that no server restart is required to test changes to a form. From this definition an instance is created for the unique display of a form. A form instance is intended for use by a single user, and should not be used repeatedly. However, it is possible to reuse an instance of a user. So a form can be opened again later with the current content and continue to be processed. 

String formFilePath = "/path/to/my/form.xml";
DefinitionFactory factory = DefinitionFactory.getInstance();
FormDefinition formDefinition = factory.loadDefinition(formFilePath);
FormContext form = FormContext.createFormContext(request, formDefinition);

In the header of the HTML file, the resources must be referenced that are needed for the presentation and execution of the form. That are especially CSS and Javascript files. All the necessary resources for the current request are registered by the previous generation of the form instance. These can be embedded into the head element by the method FormContext.getAllResourceIncludes. 

<head>
  ...
  <%= form.getAllResourceIncludes(request) %>
</head>

The display of the form in the JSP occur via the HtmlFormRenderer. This is thread safe and can be centralized or kept as static variable in a JSP. The method renderForm renders the form and is available in different parameter combinations. Possible parameter are:

  • form The form instance.
  • out The JspWriter of the page.
  • encoding Here should be specified the same encoding as in the XML header. The default encoding of the system is used if no encoding is specified.
  • nextPage Default landing page after submit the form. The actual landing page can be changed in form.
HtmlFormRenderer renderer = new HtmlFormRenderer();
renderer.renderForm(form, out, "UTF-8", "submission.jsp");

SessionObserver for the release of unused forms

Form instances is kept in memory until calling their close or release method. This usually happens automatically when you submit a form. However, often the user close the browser or simply jump to another page without save a form or cancel.

To remove unused forms from memory, there are two mechanisms that are already made available by the *FormEngine. One of these mechanisms is the SessionObserver. Is a form generated with the request object by FormContext.createFormContext and is the SessionObserver registered in the web.xml, the form instance will be closed and removed from memory when the current session expired. To activate this mechanism, SessionObserver only need to be registered as an SessionListener. 

<listener>
  <listener-class>de.imatics.j2ee.SessionObserver</listener-class>
</listener>