Using java in jails

Beyond the basic features outlined on the main page, jails has several more nuanced capabilities.

SimpleForm

SimpleForm can be binded to an object to preload a form with values from that object. it can also be assigned an identity field that can be used to update the object. Or the identity field can be marked in the Object itself using the IdentifyBy annotation.

SimpleForm also has the ability to be repeatable, and bound to more than one object.

SimpleValidator

SimpleValidator by default validates constraints first assigned to the group "RequiredConstraints.class" (Found in org.jails.form), and then "Default.class" (any constraint not assigned to a group), it does so iteratively in order to not overwhelm the user with validation errors. However, group checks can be explicitly passed in to the validation methods.

SimpleValidator also provides the ability to validating params against an existing Object, not changing the state of that object unless the validation is successful.

SimpleValidator uses SimpleMapper to map properties to an Objects/Getters and setters, this can be changed by calling the constructor with a custom Mapper object.

SimpleMapper

SimpleMapper is the default implementation of the Mapper that recursively converts a MapString, String[] to an Object and vice versa. It also provides the ability to map to an from a List of Objects (returning a map with indexed keys, in the latter case).

SimpleMapper is composed of a PropertyParser, and several handler objects that handle situations that may arise, for example, when properties exist for an Object's member class that is null.

The default parser handles properties named in the following convention (based on our ModelBean from the main page):

modelBean.name
modelBean.size
modelBean.dateCreated

//now indexed
modelBean[0].name
modelBean[0].size
modelBean[0].dateCreated

nestedProperties are allowed to any depth desired, for example:.

myObject.person.address.country.code.id

First it checks to see if nested properties are allowed on a given property (you can set this in your fields using the AcceptsNestedProperties annotation, or annotation your class with AcceptsNestedProperties, and annotating fields with RejectNestedProperties). If a field does not accept nested properties, it is just silently ignored, otherwise, if the member object is not null, the nested property will be set..

If a nested property maps to a member object that is null, it attempts to create a new instance, and populate it. If it is unsuccessful it fails silently.

If the Object is annotated with IdentifyBy, and a property matches that field, it will be ignored by the mapper, unless a LoadObjectHandler has been set, in which case, it will attempt to load that object using the id value supplied.

All of these cases are handled by the PropertyHandler assigned to the Mapper. In SimpleMapper the default PropertyHandler is SimplePropertyHandler, which is composed of two NullObjectHandlers, which conditional handle null member objects as described above. Custom Mapper implementations can provided their own handlers as needed.

SimpleForm Taglib and Controllers

The form taglib is designed so that it can can be tied into existing applications without having to adhere to any naming or routing conventions. However, additional capabilities are providing if you are interested in updating other parts of your application.

The SimpleForm taglib sets hidden properties that contain information about the state of the form.

There are the action hidden parameters in the form of:

//action params
_formName_method
//action param values
(new|edit|delete|show)

//submit param
_formName_action_submit
//submit param values
action_(new|edit|delete|show)

//if identifyBy is provided
formName.{idenityFieldName}

These parameters are used to determined whether a form is submitted, where to route the form, and how to uniquely idenitify the object the data being submitted is associated with. All this can be done with SimpleFormRouter.