Integration in einen Servlet-Container

Libraries

Die Distribution besteht ausschließlich aus Libraries, die in den Classpath der Web-Anwendung kopiert werden müssen. Einige der Libraries werden nur für bestimmte Funktionalitäten benötigt und sind optional. Die Java XML-Streaming-API steht ab J2EE-Spezifikation 5.0 standardmäßig zur Verfügung, so dass diese Libraries auch nur in älteren Implementierungen eingebunden werden müssen.
Details zu den einzelnen Libraries sind in der Datei lib/libraries.txt enthalten.

Filterkonfiguration

Zur Integration in einen Servlet-Container werden drei Filter benötigt. Das URL-Pattern sollte so allgemein wie möglich gehalten werden - am besten "/*", damit die Filter möglichst von jedem Request durchlaufen werden. So kann jeder Filter anhand der jeweilgen URL entscheiden, ob er für einen Request aktiv werden muss. Nicht für die *FormEngine relevante Requests werden einfach an den nächsten Filter in der Filterkette weiter gereicht. (Da die Filter auch auf Requests reagieren sollen, die vom Browser aus relativen Pfad-Angaben erzeugt werden, insbesondere in CSS-Dateien, kann das Mapping nicht auf einen bestimmten Pfad gelegt werden.)

<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
Stellt verschiedene Standard-Icons bereits, die in dem Standard-CSS-Dateien für die Formulare verwendet werden.
ActionFilter
Leitet per AJAX aufgerufene Action-Requests an die jeweilige Java-Methode weiter. Dazu zählen z.B. spezielle Renderer-Aktionen, wie das Hinzufügen und Entfernen von Zeilen in Repeat-Tabellen.
SubmissionFilter
Ählich wie beim ActionFilter werden hierüber Aktionen per AJAX ausgeführt. Der SubmissionFilter behandelt jedoch speziell Requests mit denen die Werte aus dem Formular zum Server gesendet werden.

Formular-Servlet

Es gibt ein Standard-Servlet zur Anzeige von Formularen, die über eine XML-Definition deklariert sind.
Das de.imatics.forms.render.html.FormServlet kann optional über die web.xml aktiviert werden. Die Funktionalität steht aber standardmäßig auch durch die bereits eingebundenen Filter zur Verfügung, wenn der Url-Pfad mit dem Präfix /form/ beginnt. Wenn die XML-Definition der Formulare als Resource im Classpath vorliegen, kann der Pfad auf die Formular-Definition als Parameter übergeben werden oder als Pfad in der URL angegeben werden.

Der Aufruf
/form/path/to/form
Lädt dann die Formular-Definition aus der Datei form.xml im Package path.to.

Dieser Aufruf zur Anzeige von Formularen ist in erster Linie zum Testen von Formularen hilfreich oder wird für Formulare in Popup-Dialogen genutzt.

Integration in eine JSP

Da die *FormEngine XHTML-Code generiert, sollte die HTML-Seite als DOCTYPE ebenfalls XHTML deklarieren.

<?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">

Als erstes muss aus einer Formular-Definition eine Instanz erzeugt werden. Formular-Definitionen können über die API erzeugt werden oder die Deklaration aus einer XML-Definition geladen werden. Die Methode loadDefinition erhält als Parameter den Pfad auf eine Resource-Datei aus dem Classpath und sorgt intern bereits für das Cachen von geladenen Formular-Definitionen. So müssen erzeugte FormDefinition für mehrfache die Verwendungen eines Formulars nicht zusätzlich gecacht werden. Der interne Cache sorgt zusätzlich für eine Aktualisierung, wenn die XML-Datei modifiziert wird, so dass kein Server-Neustart erforderlich ist, um Änderung an einem Formular zu testen. Aus dieser Definition wird dann eine Instanz für die einmalige Ausgabe eines Formulars erzeugt. Eine Formular-Instanz ist für die Verwendung durch einen einzigen Users bestimmt, und darf nicht mehrfach verwendet werden. Allerdings ist es möglich, eine Instanz für einen Benutzer wiederzuverwenden. So kann ein Formular später mit den aktuellen Inhalten wieder geöffnet und weiter bearbeitet werden.

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

In den Header der Html-Datei müssen die Ressourcen eingetragen werden, die für die Darstellung Ausführung des Formulars benötigt werden. Das sind vor allem CSS- und Javascript-Dateien. Beim vorherigen Erzeugen der Formular-Instanz werden bereits alle notwendigen Ressourcen für den aktuellen Request registriert. Diese können dann über die Methode FormContext.getAllResourceIncludes in das head-Element der Seite eingebettet werden.

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

Die Ausgabe des Formular in der JSP erfolgt über den HtmlFormRenderer. Dieser ist thread safe und auch zentral oder als statische Variable in einer JSP gehalten werden. Die Methode renderForm rendert dan ndas gesamte Formular und stehtin verschiedenen Parameter-Kombinationen zur Verfügung. Mögliche Parameter sind.

form Die Formular-Instanz.
out Der JspWriter der Seite
encoding Hier sollte dasselbe Encoding, wie im XML-Header angegeben werden. Ohne Angabe eines Encodings wird das Stadnard-Encoding des Systems verwendet.
nextPage Standard-Folgeseite nach dem Submit des Formulars. Die tatsächliche Zielseite kann durch Angaben im Formular noch geändert werden

HtmlFormRenderer renderer = new HtmlFormRenderer();
renderer.renderForm(form, out, "UTF-8", "submission.jsp");

SessionObserver zur Freigabe unbenutzter Formulare

Formular-Instanzen werden solange im Speicher gehalten, bis deren close oder release Methode aufgerufen wird. Das geschieht normalerwesie automatisch beim Submit eines Formulars. Es kommt jedoch häufig vor, dass der Anwender den Browser schließt oder einfach auf eine andere Seite springt ohne ein Formular zu speichern oder abzubrechen.

Um unbenutzte Formulare aus dem Speicher zu entfernen, gibt es zwei Mechanismen, die bereits von der *FormEngine zur Verfügung gestellt werden. Einer dieser Mechanismen ist der SessionObserver. Wird ein Formular über FormContext.createFormContext mit dem Request-Objekt erzeugt und ist der SessionObserver in der web.xml registriert, wird die Formular-Instanz geschlossen und aus dem Speicher entfernt, sobald die aktuelle Session abläuft. Um diesen Mechanismus zu aktivieren, muss lediglich der SessionObserver als SessionListener registriert werden.

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