The Elements of the Spring Web Flow Configuration File

0
111
9 min read

Let’s take a look at the XML Schema Definition (XSD) file of the Spring Web Flow configuration file. To make the file more compact and easier to read, we have removed documentation and similar additions from the file. The complete file is downloadable from http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd.

An XSD file is a file that is used to describe an XML Schema, which in itself is a W3C recommendation to describe the structure of XML files. In this kind of definition files, you can describe which elements can or must be present in an XML file. XSD files are primarily used to check the validity of XML files that are supposed to follow a certain structure. The schema can also be used to automatically create code, using code generation tools.

The elements of the Spring configuration file are:

flow

The root element of the Spring Web Flow definition file is the flow element. It has to be present in all configurations because all other elements are sub-elements of the flow tag, which defines exactly one flow. If you want to define more than one flow, you will have to use the same number of flow tags. As every configuration file allows only one root element, you will have to define a new configuration file for every flow you want to define.

attribute

Using  the attribute tag, you can define metadata for a flow. You can use this metadata to change the behavior of the flow.

secured

The secured tag is used to secure your flow using Spring Security. The element is defined like this:

<xsd:complexType name="secured">
<xsd:attribute name="attributes"
type="xsd:string"
use="required" />
<xsd:attribute name="match"
use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="any" />
<xsd:enumeration value="all" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:complexType>

If you want to use the secured element, you will have to at least define the attributes attribute. You can use the attributes element to define roles that are allowed to access the flow, for example. The match attribute defines whether all the elements specified in the attributes attribute have to match successfully (all), or if one of them is sufficient (any).

persistence-context

The persistence-context element enables you to use a persistence provider in your flow definition. This lets you persist database objects in action-states.

To use persistence-context tag, you also have to define a data source and configure the persistence provider of your choice (for example, Hibernate or the Java Persistence API) in your Spring application context configuration file.

The persistence-context element is empty, which means that you just have to add

<persistence-context />

to your flow definition, to enable its features.

var

The var element can be used to define instance variables, which are accessible in your entire flow. These variables are quite important, so make sure that you are familiar with them. Using var elements, you can define model objects. Later, you can bind these model objects to the forms in your JSP web sites and can store them in a database using the persistence features enabled with the persistence-context element.  Nevertheless, using instance variables is not mandatory, so you do not have to define any, unless required in your flow. The element is defined as shown in the following snippet from the XSD file:

<xsd:element name="var" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="class" type="type" use="required" />
</xsd:complexType>
</xsd:element>

The element has two attributes that are both required. The instance variable you want to define needs a name, so that you can reference it later in your JSP files. Spring Web Flow also needs to know the type of the variable, so you have to define the class attribute with the class of your variable.

input

You can use the input element to pass information into a flow. When you call a flow, you can (or will have to, depending on whether the input element is required or not) pass objects into the flow. You can then use these objects to process your flow. The XML Schema definition of this element looks like this:

<xsd:complexType name="input">
<xsd:attribute name="name" type="expression" use="required" />
<xsd:attribute name="value" type="expression" />
<xsd:attribute name="type" type="type" />
<xsd:attribute name="required" type="xsd:boolean" />
</xsd:complexType>

The input element possesses certain attributes, of which only the name attribute is required. You have to specify a name for the input argument, which you can use to reference the variable in your flow. The value attribute is used to specify the value of the attribute, for example, if you want to define a default value for the variable. You can also define a type (for example int or long) for the variable if you want a specific type of information. A type conversion will be tried if the argument passed to the flow does not match the type you expect. With the required attribute, you can control if the user of your flow has to pass in a variable, or if the input attribute is optional.

output

While you can define input parameters with the input element, you can specify return values with the output element. These are variables that will be passed to your end-state as the result value of your flow. Here’s the XML Schema definition of the output element:

<xsd:complexType name="output">
<xsd:attribute name="name" type="expression" use="required" />
<xsd:attribute name="value" type="expression" />
<xsd:attribute name="type" type="type" />
<xsd:attribute name="required" type="xsd:boolean" />
</xsd:attribute>
</xsd:complexType>

The definition is quite similar to the input element. You can also see that the name of the output element is required. Otherwise, you have no means of referencing the variable from your end-state. The value attribute is the value of your variable, for example, the result of a computation or a user returned from a database. Of course, you can also specify the type you expect your output variable to be. As with the input element, a type conversion will be attempted if the type of the variable does not match the type specified here. The required attribute will check if nothing was specified, or the result of a computation is null. If it is null, an error will be thrown.

 

actionTypes

Per se, this is not an element which you can use in your flow definition, but it is a very important part of the XML Schema definition, referenced by many other elements. The definition is quite complex and looks like this:

<xsd:group name="actionTypes">
<xsd:choice>
<xsd:element name="evaluate">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="attribute"
type="attribute"
minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="expression"
type="expression"
use="required" />
<xsd:attribute name="result"
type="expression"
use="optional" />
<xsd:attribute name="result-type"
type="type"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="render">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="attribute"
type="attribute"
minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="fragments"
type="xsd:string"
use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="set">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="attribute"
type="attribute"
minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="name"
type="expression"
use="required" />
<xsd:attribute name="value"
type="expression"
use="required" />
<xsd:attribute name="type" type="type" />
</xsd:complexType>
</xsd:element>
</xsd:choice>
</xsd:group>

actionTypes is a group of sub-elements, namely evaluate, render, and set. Let’s go through the single elements to understand how the whole definition works.

evaluate

With the evaluate element, you can execute code based on the expression languages. As described by the above source code, the element has three attributes; one of them is required. The expression attribute is required and executes the code that you want to run. The result value of the expression, if present, can be stored in the result attribute. Using the result-type attribute, you can convert the result value in the specified type, if needed. Additionally, you can define attributes using a sub-element of the attribute element.

render

Use the render element to partially render content of a web site. Using the required fragments attribute, you can define which fragments should be rendered. When the link on a web site is clicked the entire web site is not a re-load. Spring JavaScript allows you to update chosen parts of your web page. The remaining web site will not be reloaded, which can greatly enhance the performance of your web application. As is the case with the evaluate element, you can also specify additional attributes using the attribute sub-element.

set

The set element can be used to set attributes in one of the Spring Web Flows scopes. With the name attribute you can define where (in which scope) you want to define the attribute, and how it should be called. The following short source code illustrates how the set element works:

<set name="flowScope.myVariable" value="myValue" type="long" />

As you can see, the name consists of the name of the scope and the name of your variable, delimited by a dot (.). Both the name attribute and the value attribute are required. The value is the actual value of your variable. The type attribute is optional and describes the type of your variable. As before, you can also define additional attributes using the attribute sub-element.

LEAVE A REPLY

Please enter your comment!
Please enter your name here