Child pages
  • Type Conversion

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Routine type conversion in the framework is transparent. Generally, all you need to do is ensure that HTML inputs have names that can be used in OGNL expressions. (HTML inputs are form elements and other GET/POST parameters.)

...

Built in Type Conversion Support

Type Conversion is implemented by XWork.

...

  • Enumerations
  • BigDecimal and BigInteger

...

  • Use OGNL expressions - the framework will automatically take care of creating the actual objects for you.
  • Use JavaBeans! The framework can only create objects that obey the JavaBean specification, provide no-arg constructions and include getters and setters where appropriate.
  • Remember that person.name will call getPerson().setName(). If the framework creates the Person object for you, it remember that a setPerson method must also exist.
  • The framework will not instantiate an object if an instance already exists. The PrepareInterceptor or action's constructor can be used to create target objects before type conversion.
  • Wiki MarkupFor lists and maps, use index notation, such as _people\[0\].name_ or _friends\['patrick'\].name_. Often these HTML form elements are being rendered inside a loop. For [JSP Tags], use the iterator tag's status attribute. For [FreeMarker Tags], use the special property $\{foo_index\}\[\].
  • For multiple select boxes, it isn't possible to use index notation to name each individual item. Instead, name your element people.name and the framework will understand that it should create a new Person object for each selected item and set its name accordingly.

...

...

To allow Struts to recognize that a conversion error has occurred, the converter class needs to throw XWorkException or preferably TypeConversionException.

...

Within the conversion file, name the action's property and the Converter to apply to it:

...

Type conversion can also be specified via Annotations within the action.

...

Example: A custom converter is required for the Amount property of a Measurement bean. The Measurement class cannot be modified as its located within one of the application's dependencies. The action using Measurement implements ModelDriven<Measurement> so it cannot apply converters to the properties directly.
Solution: The conversion file needs to be in the same location of the classpath as Measurement. Create a directory in your source or resources tree matching the package of Measurement and place the converters file there.
eg. for com.acme.measurements.Measurement, create a file in the application source/resources at /com/acme/measurements/Measurement-conversion.properties:

...

Applying a Type Converter for an application

Application-wide converters can be specified in a file called xwork-convertersconversion.properties located in the root of the classpath.

...

A Simple Example

...

The framework ships with a base helper class that simplifies converting to and from Strings, org.apache.struts2.util.StrutsTypeConverter. The helper class makes it easy to write type converters that handle converting objects to Strings as well as from Strings.

From the JavaDocs:

...

Advanced Type Conversion

The framework also handles advanced type conversion cases, like null property handling and converting values in Maps and Collections, and type conversion error handling.

...

Null property handling will automatically create objects where null references are found.

...

Collection and Map Support

...

The framework supports ways to discover the object type for elements in a collection. The discover is made via an ObjectTypeDeterminer. A default implementation is provided with the framework. The Javadocs explain how Map and Collection support is discovered in the DefaultObjectTypeDeterminer.

...

Additionally, you can create your own custom ObjectTypeDeterminer by implementing the ObjectTypeDeterminer interface. There is also an optional ObjectTypeDeterminer that utilizes Java 5 generics. See the Annotations page for more information.

...

For an example, see the following two classes:

...

To enable type conversion, put the instruction KeyProperty_fooCollection=id in the MyAction-conversion.properties file. This technique allows use of the idiom fooCollection(someIdValue) to obtain the Foo object with value someIdValue in the Set fooCollection. For example, fooCollection(22) would return the Foo object in the fooCollection Collection whose id property value was 22.

...

The framework automatically converts the type of the parameter sent in to the type of the key property using type conversion.

Wiki MarkupUnlike Map and List element properties, if {{fooCollection(22)}} does not exist, it will not be created. If you would like it created, use the notation {{fooCollection.makeNew\[index\]}} where _index_ is an integer 0, 1, and so on. Thus, parameter value pairs {{fooCollection.makeNew\[0\]=Phil}} and {{fooCollection.makeNew\[1\]=John}} would add two new Foo Objects to {{fooCollection \ -\-}} one with name property value {{Phil}} and the other with name property value {{John}}. However, in the case of a Set, the {{equals}} and {{hashCode}} methods should be defined such that they don't only include the {{id}} property. Otherwise, one element of the null {{id}} properties Foos to be removed from the Set.

An advanced example for indexed Lists and Maps

Here is the model bean used within the list. The KeyProperty for this bean is the id attribute.

...

The Action has a beanList attribute initialized with an empty ArrayList.

...

These conversion.properties tell the TypeConverter to use MyBean instances as elements of the List.

...

  • When submitting this via a form, the id value is used as KeyProperty for the MyBean instances in the beanList.
  • Wiki MarkupNotice the () notation\! Do not use \ [\] notation, which is for Maps only\!
  • The value for name will be set to the MyBean instance with this special id.
  • The List does not have null values added for unavailable id values. This approach avoids the risk of OutOfMemoryErrors!

...

Type Conversion Error Handling

Type conversion error handling provides a simple way to distinguish between an input validation problem and an input type conversion problem.

...

There are two ways the error reporting can occur:

...

The following is an example of this problem:

...

Although to the developer the area.setUnits(enumValue) method only accepts a UnitsOfArea enumeration, due to erasure the signature of this method is actually setUnits(java.lang.Enum). The framework does not know that the parameter is a UnitsOfArea and when it attempts to instantiate the Enum an exception is thrown (java.lang.IllegalArgumentException: java.lang.Enum is not an enum type).

...