net.sf.chainedoptions
Interface ChainedOption

All Known Implementing Classes:

AbstractChainedOption, OptionalRefreshChainedOption

public interface ChainedOption

An ChainedOption is responsible for handling an attribute in a command object, such as a Struts ActionForm or plain Java Bean, and the available options for this attribute.

To fulfil this responsibility, implement the retrieveOptions(Object, Object)method, which should extract any values that this ChainedOption depends from the command object and retrieve the available options for these values. Also, implement the updateValue(Object, List, Object)method to check the current value of the managed attribute against the current list of available options and optionally update the value if the current one is not present in the list.

Example: The value object is a Query object of some sort. It has a region property and a country property. Our ChainedOption corresponds to the country property in the query object. The ChainedOptionManager managing this ChainedOption decides that a new list of available countries is needed, perhaps because the region property has changed. The ChainedOptionManager calls retrieveOptions(Object, Object)method on the ChainedOption, which knows how to get the countries that match the current region in the query object.

The ChainedOptionManager then calls updateValue(Object, List, Object)on the ChainedOption, which knows how to set the country property of the query object. It takes the list of available options as a parameter. The updateValue method checks if the current country value in the query exists in the list of options. If it exists in the list, nothing needs to be done. However, if the current value does not exist in the list, the query object needs a default value. The ChainedOption then calculates a default value, possibly by calling its ChainedOptionStrategy, and the country property in the query object is set to the default value.

Author:

Mattias Arthursson, Ulrik Sandberg

See Also:

AbstractChainedOption, ChainedOptionManager, AbstractChainedOption

Method Summary

java.lang.String	getOptionsKey() Get the key that identifies the list of options corresponding to this ChainedOption.
ChainedOptionStrategy	getStrategy(java.lang.Object command) Get the ChainedOptionStrategyto use for filtering and sorting values as well as for selecting the default value.
java.util.List	retrieveOptions(java.lang.Object command, java.lang.Object context) Retrieve a value List for this ChainedOption corresponding to the current values in the command that this ChainedOption depends on.
void	updateValue(java.lang.Object command, java.util.List options, java.lang.Object context) Check the command if it needs to be updated.

Method Detail

retrieveOptions

java.util.List retrieveOptions(java.lang.Object command,
                               java.lang.Object context)

Retrieve a value List for this ChainedOption corresponding to the current values in the command that this ChainedOption depends on. This method may use a BeanConverterto translate Java Beans to LabelValueBeanobjects and an ChainedOptionStrategyto perform additional modifications to the option list.

Parameters:

command - Command object to use when extracting values that the ChainedOption depends on.

context - may contain any context that might be interesting for retreiving valid options. E.g. a HttpServletRequest object can be supplied as context for a Strategy to perform filtering based on user access.

Returns:

A list of LabelValueBeanobjects.

updateValue

void updateValue(java.lang.Object command,
                 java.util.List options,
                 java.lang.Object context)

Check the command if it needs to be updated. The options list may be used for choosing a default value.

Parameters:

command - The command object that may be updated.

options - A list of LabelValueBeanobjects to choose from.

context - may contain any context that might be interesting for retreiving valid options. E.g. a HttpServletRequest object can be supplied as context for a Strategy to perform filtering based on user access.

getOptionsKey

java.lang.String getOptionsKey()

Get the key that identifies the list of options corresponding to this ChainedOption.

Returns:

the key as a String.

getStrategy

ChainedOptionStrategy getStrategy(java.lang.Object command)

Get the ChainedOptionStrategyto use for filtering and sorting values as well as for selecting the default value.

Parameters:

command - the command to use for selecting the correct Strategy.

Returns:

the ChainedOptionStrategy to use based on the current situation. Some implementations may have several strategies to choose from, and this method is responsible for choosing the correct one in each situation based on the current values in the command.