org.apache.click.util
Class ContainerUtils

java.lang.Object
  org.apache.click.util.ContainerUtils

public class ContainerUtils
extends Object

Provides Container access and copy utilities.

Constructor Summary

ContainerUtils()

Method Summary

static void	copyContainerToObject(Container container, Object object) Populate the given object attributes from the Containers field values.
static void	copyContainerToObject(Container container, Object object, List<Field> fieldList) Populate the given object attributes from the Containers field values.
static void	copyObjectToContainer(Object object, Container container) Populate the given Container field values from the object attributes.
static void	copyObjectToContainer(Object object, Container container, List<Field> fieldList) Populate the given Container field values from the object attributes.
static Control	findControlByName(Container container, String name) Find and return the first control with a matching name in the specified container.
static Form	findForm(Control control) Find and return the specified controls parent Form or null if no Form is present.
static List<Button>	getButtons(Container container) Return the list of Buttons for the given Container, recursively including any Fields contained in child containers.
static List<Field>	getErrorFields(Container container) Return a list of container fields which are not valid, not hidden and not disabled.
static Map<String,Field>	getFieldMap(Container container) Return a map of all Fields for the given Container, recursively including any Fields contained in child containers.
static List<Field>	getFields(Container container) Return the list of Fields for the given Container, recursively including any Fields contained in child containers.
static List<Field>	getFieldsAndLabels(Container container) Return the list of Fields for the given Container, recursively including any Fields contained in child containers.
static List<Field>	getHiddenFields(Container container) Return the list of hidden Fields for the given Container, recursively including any Fields contained in child containers.
static List<Field>	getInputFields(Container container) Return the list of input Fields (TextField, Select, Radio, Checkbox etc).
static Control	insert(Container container, Control control, int index, Map<String,Control> controlMap) Add the given control to the container at the specified index, and return the added instance.
static boolean	remove(Container container, Control control, Map<String,Control> controlMap) Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.
static Control	replace(Container container, Control currentControl, Control newControl, int controlIndex, Map<String,Control> controlMap) Deprecated. this method was used for stateful pages, which have been deprecated

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContainerUtils

public ContainerUtils()

Method Detail

copyContainerToObject

public static void copyContainerToObject(Container container,
                                         Object object,
                                         List<Field> fieldList)

Populate the given object attributes from the Containers field values.

If a Field and object attribute matches, the object attribute is set to the Object returned from the method Field.getValueObject(). If an object attribute is a primitive, the Object returned from Field.getValueObject() will be converted into the specific primitive e.g. Integer will become int and Boolean will become boolean.

The fieldList specifies which fields to copy to the object. This allows one to include or exclude certain Container fields before populating the object.

The following example shows how to exclude disabled fields from populating a customer object:

 public void onInit() {
     List formFields = new ArrayList();
     for(Iterator it = form.getFieldList().iterator(); it.hasNext(); ) {
         Field field = (Field) formFields.next();
         // Exclude disabled fields
         if (!field.isDisabled()) {
             formFields.add(field);
         }
     }
     Customer customer = new Customer();
     ContainerUtils.copyContainerToObject(form, customer, formFields);
 }
 

The specified Object can either be a POJO (plain old java object) or a Map. If a POJO is specified, its attributes are populated from matching container fields. If a map is specified, its key/value pairs are populated from matching container fields.

Parameters:

container - the fieldList Container

object - the object to populate with field values

fieldList - the list of fields to obtain values from

Throws:

IllegalArgumentException - if container, object or fieldList is null

copyContainerToObject

public static void copyContainerToObject(Container container,
                                         Object object)

Populate the given object attributes from the Containers field values.

Parameters:

container - the Container to obtain field values from

object - the object to populate with field values

See Also:

copyContainerToObject(org.apache.click.control.Container, java.lang.Object, java.util.List)

copyObjectToContainer

public static void copyObjectToContainer(Object object,
                                         Container container,
                                         List<Field> fieldList)

Populate the given Container field values from the object attributes.

If a Field and object attribute matches, the Field value is set to the object attribute using the method Field.setValueObject(java.lang.Object). If an object attribute is a primitive it is first converted to its proper wrapper class e.g. int will become Integer and boolean will become Boolean.

The fieldList specifies which fields to populate from the object. This allows one to exclude or include specific fields.

The specified Object can either be a POJO (plain old java object) or a Map. If a POJO is specified, its attributes are copied to matching container fields. If a map is specified, its key/value pairs are copied to matching container fields.

Parameters:

object - the object to obtain attribute values from

container - the Container to populate

fieldList - the list of fields to populate from the object attributes

copyObjectToContainer

public static void copyObjectToContainer(Object object,
                                         Container container)

Populate the given Container field values from the object attributes.

Parameters:

object - the object to obtain attribute values from

container - the Container to populate

See Also:

copyObjectToContainer(java.lang.Object, org.apache.click.control.Container, java.util.List)

findControlByName

public static Control findControlByName(Container container,
                                        String name)

Find and return the first control with a matching name in the specified container.

If no matching control is found in the specified container, child containers will be recursively scanned for a match.

Parameters:

container - the container that is searched for a control with a matching name

name - the name of the control to find

Returns:

the control which name matched the given name

findForm

public static Form findForm(Control control)

Find and return the specified controls parent Form or null if no Form is present.

Parameters:

control - the control to check for Form

Returns:

the controls parent Form or null if no parent is a Form

getButtons

public static List<Button> getButtons(Container container)

Return the list of Buttons for the given Container, recursively including any Fields contained in child containers.

Parameters:

container - the container to obtain the buttons from

Returns:

the list of contained buttons

getErrorFields

public static List<Field> getErrorFields(Container container)

Return a list of container fields which are not valid, not hidden and not disabled.

The list of returned fields will exclude any Button fields.

Parameters:

container - the container to obtain the invalid fields from

Returns:

list of container fields which are not valid, not hidden and not disabled

getFieldMap

public static Map<String,Field> getFieldMap(Container container)

Return a map of all Fields for the given Container, recursively including any Fields contained in child containers.

The map's key / value pair will consist of the control name and instance.

Parameters:

container - the container to obtain the fields from

Returns:

the map of contained fields

getFields

public static List<Field> getFields(Container container)

Return the list of Fields for the given Container, recursively including any Fields contained in child containers.

Parameters:

container - the container to obtain the fields from

Returns:

the list of contained fields

getFieldsAndLabels

public static List<Field> getFieldsAndLabels(Container container)

Return the list of Fields for the given Container, recursively including any Fields contained in child containers. The list of returned fields will exclude any Button and FieldSet fields.

Parameters:

container - the container to obtain the fields from

Returns:

the list of contained fields

getHiddenFields

public static List<Field> getHiddenFields(Container container)

Return the list of hidden Fields for the given Container, recursively including any Fields contained in child containers. The list of returned fields will exclude any Button, FieldSet and Label fields.

Parameters:

container - the container to obtain the fields from

Returns:

the list of contained fields

getInputFields

public static List<Field> getInputFields(Container container)

Return the list of input Fields (TextField, Select, Radio, Checkbox etc). for the given Container, recursively including any Fields contained in child containers. The list of returned fields will exclude any Button, FieldSet and Label fields.

Parameters:

container - the container to obtain the fields from

Returns:

the list of contained fields

insert

public static Control insert(Container container,
                             Control control,
                             int index,
                             Map<String,Control> controlMap)

Add the given control to the container at the specified index, and return the added instance.

Please note: an exception is raised if the container contains a control with the same name as the given control. It is the responsibility of the caller to replace existing controls.

Also note if the specified control already has a parent assigned, it will automatically be removed from that parent and inserted as a child of the container instead.

This method is useful for developers needing to implement the Container interface but cannot for one reason or another extend from AbstractContainer. For example if the Container already extends from an existing Control such as a Field, it won't be possible to extend AbstractContainer as well. In such scenarios instead of reimplementing insert, one can delegate to this method.

For example, a custom Container that extends Field and implements Container could implement the insert method as follows:

 public class MyContainer extends Field implements Container {

     public Control insert(Control control, int index) {
         return ContainerUtils.insert(this, control, index, getControlMap());
     }

     ...
 } 

Parameters:

container - the container to insert the given control into

control - the control to add to the container

index - the index at which the control is to be inserted

controlMap - the container's map of controls keyed on control name

Returns:

the control that was added to the container

Throws:

IllegalArgumentException - if the control is null or if the control and container is the same instance

IndexOutOfBoundsException - if index is out of range (index < 0 || index > container.getControls().size())

replace

public static Control replace(Container container,
                              Control currentControl,
                              Control newControl,
                              int controlIndex,
                              Map<String,Control> controlMap)

Deprecated. this method was used for stateful pages, which have been deprecated

Replace the current control in the container at the specified index, and return the newly added control.

Please note if the new control already has a parent assigned, it will automatically be removed from that parent and inserted as a child of the container instead.

This method is useful for developers needing to implement the Container interface but cannot for one reason or another extend from AbstractContainer. For example if the Container already extends from an existing Control such as a Field, it won't be possible to extend AbstractContainer as well. In such scenarios instead of reimplementing replace, one can delegate to this method.

For example, a custom Container that extends Field and implements Container could implement the replace method as follows:

 public class MyContainer extends Field implements Container {

     public Control replace(Control currentControl, Control newControl) {
         int controlIndex = getControls().indexOf(currentControl);
         return ContainerUtils.replace(this, currentControl, newControl,
             controlIndex, getControlMap());
     }

     ...
 } 

Parameters:

container - the container to insert the new control into

currentControl - the control currently contained in the container

newControl - the control to replace the current control contained in the container

controlIndex - the index of the current control in the container

controlMap - the container's map of controls keyed on control name

Returns:

the new control that replaced the current control

Throws:

IllegalArgumentException - if the currentControl or newControl is null

IllegalStateException - if the controlIndex = -1

remove

public static boolean remove(Container container,
                             Control control,
                             Map<String,Control> controlMap)

Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.

This method is useful for developers needing to implement the Container interface but cannot for one reason or another extend from AbstractContainer. For example if the Container already extends from an existing Control such as a Field, it won't be possible to extend AbstractContainer as well. In such scenarios instead of reimplementing remove, one can delegate to this method.

For example, a custom Container that extends Field and implements Container could implement the remove method as follows:

 public class MyContainer extends Field implements Container {

     public boolean remove (Control control) {
         return ContainerUtils.remove(this, control, getControlMap());
     }

     ...
 } 

Parameters:

container - the container to remove the given control from

control - the control to remove from the container

controlMap - the container's map of controls keyed on control name

Returns:

true if the control was removed from the container

Throws:

IllegalArgumentException - if the control is null