Content

Form and data binding

Each client / server application must interract with a user. Gaia supports this requirement with the FormController class.

FormController is an abstract superclass for all form-based controllers. It supports data binding - it extracts from given data objects data requested by the form, prepares it for ApplicationResponse and also processes returned changed data from a client.

Form controller works with a form description in XML format. So you can use the same form XML file for the Swing client form and also on server side. FormController extracts binding attributes from that XML file and creates its internal bind-mapping. Then - when constructing response for client - it mines property values defined in binding from given data object and sends it to the client to show in UI.

There are some methods you have to implement in your subclass:

• getInstruction(Context) - to get an instruction for client (such as "display form", etc.)
• getFormId(Context) - to get a form id (form name)
• getObject(Context) - to get a processed data object
• getObjectsForListModel(String, Context) - to get the data objects for given list model

There is the method displayForm(Context) which creates completed application response with extracted and converted values from the context's data object and with the data for list models. This method invokes all of above methods.

The data extraction and data binding for displaying data on the client is processed in method buildFormObject(Object, String, Context) in these steps:

1. the form XML file is parsed and loaded to a FormDescriptor instance
2. it traverses its FormItem instances to find the binding property
3. it gets the requested bound property value from given data object
4. it converts this value (if necessary) and stores it to the internally created instance of ValueObject
5. if the bound property value is not a null, primitive value or enumeration constant, it takes this value as a new data object and repeats the step 2 for the children of currently processed instance of FormItem

If you want to use this built-in mechanism but you need to modify it, you can override method getMiner() to change the tool to access data properties or getPropertyValueFromDataObject(Object, String, Context) to do the same without changing the miner.

There is also the support to process the modified data from the client. It is started with method acceptFormObject(ApplicationRequest, Context) (you have to invoke it from your code yourself). It takes the server data object (via getObject(Context) method) and incoming data from the client request, walks in client form object(s) property by property and searches the appropriate property in data object(s). When it is found, invokes method acceptFormPropertyValue(Object, Object, Object, Object, String, Context) to set changed value to the data object. Override this last method to:

• ignore derived properties (this is a term from UML, such property has a getter only, but no setter or field)
• accept the changes in the references to the other objects, this is not supported and you have to do it in subclasses (for example, you can change on the client the reference to the other object in combo box, but in client request you obtain on the server just value object with (persistent) id of newly referenced object - to get it from database and set as reference to processed object is your job in overriden method acceptFormPropertyValue(Object, Object, Object, Object, String, Context).