JavaGantt 2011.1 API

eu.beesoft.gaia.app
Class FormController

java.lang.Object
  extended by eu.beesoft.gaia.app.Controller
      extended by eu.beesoft.gaia.app.FormController

public abstract class FormController
extends Controller

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.

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

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:


Constructor Summary
FormController()
           
 
Method Summary
protected  java.lang.Object acceptFormObject(ApplicationRequest request, Context context)
          Processes an object from AbstractRequestResponse.getData() to update server data object with changes from client.
protected  java.lang.Object acceptFormPropertyValue(java.lang.Object formPropertyValue, java.lang.Object formObject, java.lang.Object dataPropertyValue, java.lang.Object dataObject, java.lang.String propertyName, Context context)
          Sets a new data property value to the given data object from the form property value and object.
protected  java.util.List<java.lang.Object> buildFormListModel(java.util.Collection<?> data, java.lang.String listModelId, java.lang.String formId, Context context)
          Returns the list of the objects for list model for the client, built from given data objects.
protected  java.lang.Object buildFormObject(java.lang.Object dataObject, java.lang.String formId, Context context)
          Creates the object for the client form.
protected  void clearRegisteredDataObjects(Context context)
           
protected  ApplicationResponse createResponse(java.lang.String instruction, java.lang.String formId, java.lang.Object object, Context context)
          Creates the response for client.
protected  ApplicationResponse displayForm(Context context)
          Creates an application response Returns a root data object for this controller and given context.
protected  FormDescriptor getForm(java.lang.String formId)
          Returns a form descriptor for given form id.
protected abstract  java.lang.String getFormId(Context context)
          Returns a form id for this controller and given context.
protected abstract  java.lang.String getInstruction(Context context)
          Returns an instruction for the newly constructed response.
 Miner getMiner()
          Gets a miner of this controller.
protected abstract  java.lang.Object getObject(Context context)
          Returns a root data object for this controller and given context.
protected  java.util.List<?> getObjectsForListModel(java.lang.String listModelId, Context context)
          Returns a list of data objects used to build the list model for the component with given id.
protected  java.lang.Object getPropertyValueFromDataObject(java.lang.Object dataObject, java.lang.String propertyName, Context context)
          Returns a value of the requested property from the given object.
protected  java.lang.Object getRegisteredDataObject(java.lang.Long id, Context context)
           
protected  java.lang.Long getRegisteredDataObjectId(java.lang.Object object, Context context)
           
protected  ApplicationResponse process(ApplicationRequest request, Context context)
          Invokes a displayForm(Context) to build the response.
protected  void registerDataObject(java.lang.Object dataObject, java.lang.Long id, Context context)
           
 void setMiner(Miner miner)
          Sets a miner for this controller.
protected  void setPropertyValueToDataObject(java.lang.Object dataObject, java.lang.String propertyName, java.lang.Object propertyValue, Context context)
          Sets a given value to the requested property of the given object.
 
Methods inherited from class eu.beesoft.gaia.app.Controller
addMapping, createContextForForward, failure, forward, getController, getMapping, returnFailure, returnSuccess, setMapping, success
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FormController

public FormController()
Method Detail

getForm

protected FormDescriptor getForm(java.lang.String formId)
Returns a form descriptor for given form id. Once created and returned form descriptor is cached for the next call. Use this method to save the server time and resources.

Parameters:
formId - - form id (name of the form file)
Returns:
form descriptor for given formId
Throws:
java.lang.RuntimeException - if form cannot be found or loaded

process

protected ApplicationResponse process(ApplicationRequest request,
                                      Context context)
Invokes a displayForm(Context) to build the response.

Specified by:
process in class Controller
Parameters:
request - - client request to process
context - - current context
Returns:
server application response

getInstruction

protected abstract java.lang.String getInstruction(Context context)
Returns an instruction for the newly constructed response.

Parameters:
context - - current context
Returns:
instruction for the response

getFormId

protected abstract java.lang.String getFormId(Context context)
Returns a form id for this controller and given context.

Parameters:
context - - current context
Returns:
form id

getObject

protected abstract java.lang.Object getObject(Context context)
Returns a root data object for this controller and given context.

Parameters:
context - - current context
Returns:
data object to display on client

displayForm

protected ApplicationResponse displayForm(Context context)
Creates an application response Returns a root data object for this controller and given context. It invokes these methods in this order:
  1. getInstruction(Context)
  2. getFormId(Context)
  3. getObject(Context)
  4. createResponse(String, String, Object, Context)

Parameters:
context - - current context
Returns:
application response

createResponse

protected ApplicationResponse createResponse(java.lang.String instruction,
                                             java.lang.String formId,
                                             java.lang.Object object,
                                             Context context)
Creates the response for client. It invokes buildFormObject(Object, String, Context) method to extract data for form from given object. Then for each list model invokes getObjectsForListModel(String, Context) to get list model data. The created and initialized application response is returned.

Parameters:
instruction - - an instruction name (fot the client)
formId - - form id (name of the form XML file)
object - - data object to display on client
context - - current context
Returns:
a newly created application response

getObjectsForListModel

protected java.util.List<?> getObjectsForListModel(java.lang.String listModelId,
                                                   Context context)
Returns a list of data objects used to build the list model for the component with given id. In this implementation throws RuntimeException to force a programmer to override it.

Parameters:
listModelId - - the id of list model component
context - - the current context
Returns:
list of objects to build requested list model

getMiner

public Miner getMiner()
Gets a miner of this controller.

Returns:
the miner

setMiner

public void setMiner(Miner miner)
Sets a miner for this controller. Miner is used to extract data from data object for form components.

Parameters:
miner - the miner to set

registerDataObject

protected void registerDataObject(java.lang.Object dataObject,
                                  java.lang.Long id,
                                  Context context)

getRegisteredDataObject

protected java.lang.Object getRegisteredDataObject(java.lang.Long id,
                                                   Context context)

getRegisteredDataObjectId

protected java.lang.Long getRegisteredDataObjectId(java.lang.Object object,
                                                   Context context)

clearRegisteredDataObjects

protected void clearRegisteredDataObjects(Context context)

buildFormObject

protected java.lang.Object buildFormObject(java.lang.Object dataObject,
                                           java.lang.String formId,
                                           Context context)
Creates the object for the client form. It obtains a form descriptor for given formId and then searches each form item for binding and item binding properties. It gets a requested property from given data object for each found binding. This process is performed on referenced data objects, too, so it extracts and converts all needed data to display on the client in given form.

Parameters:
dataObject - - root data object for data extraction
formId - - the form id
context - - the current context
Returns:
the form object with data extracted from data object

buildFormListModel

protected java.util.List<java.lang.Object> buildFormListModel(java.util.Collection<?> data,
                                                              java.lang.String listModelId,
                                                              java.lang.String formId,
                                                              Context context)
Returns the list of the objects for list model for the client, built from given data objects.

Parameters:
data - - the collection of data objects for list model
listModelId - - the id of list model (from the form XML file)
formId - - the form id
context - - the current context
Returns:
the collection of objects created from extracted data objects

getPropertyValueFromDataObject

protected java.lang.Object getPropertyValueFromDataObject(java.lang.Object dataObject,
                                                          java.lang.String propertyName,
                                                          Context context)
Returns a value of the requested property from the given object. This method is used in binding process, it redirects a call to the Miner. The miner tries to get a property via the getter, the field access and via getProperty() method for ValueObject instance (in this order). Override it if you need some special access to the requested property.

Parameters:
dataObject - - the object from which is property requested
propertyName - - the name of the requested property
context - - the current context
Returns:
requested property value

acceptFormObject

protected java.lang.Object acceptFormObject(ApplicationRequest request,
                                            Context context)
Processes an object from AbstractRequestResponse.getData() to update server data object with changes from client. Returns an updated server data object.

Parameters:
request - - the client request to process
context - - the current context
Returns:
the updated server data object

setPropertyValueToDataObject

protected void setPropertyValueToDataObject(java.lang.Object dataObject,
                                            java.lang.String propertyName,
                                            java.lang.Object propertyValue,
                                            Context context)
Sets a given value to the requested property of the given object. This method is used in the accept process, it redirects a call to the Miner.setValue(Object, String, Object). The miner tries to set a property via the setter, the field access and via setProperty() method for ValueObject instance (in this order). Override it if you need some special access to set the property.

Parameters:
dataObject - - the owner of the property
propertyName - - the name of the requested property
propertyValue - - the value to set to the property
context - - the current context

acceptFormPropertyValue

protected java.lang.Object acceptFormPropertyValue(java.lang.Object formPropertyValue,
                                                   java.lang.Object formObject,
                                                   java.lang.Object dataPropertyValue,
                                                   java.lang.Object dataObject,
                                                   java.lang.String propertyName,
                                                   Context context)
Sets a new data property value to the given data object from the form property value and object. The new data property value is: Override this method to perform the reference change to the other object (for example, via combobox) or to process derived value (this is a value of property which has a getter, but no setter and no field exists for it). Return null in these cases to stop the recoursive acceptance loop in this branch (you need to change reference to object, not referenced object properties).

This method is invoked from acceptFormObject(ApplicationRequest, Context) method.

Parameters:
formPropertyValue - - value from the form object at given propertyName
formObject - - the form object - container for formPropertyValue
dataPropertyValue - - value from the data object at given propertyName
dataObject - - the data object - container for dataPropertyValue
propertyName - - the name of the property which is processed
context - - the current context
Returns:
new data property value

JavaGantt 2011.1 API