View Javadoc

1   package net.sf.chainedoptions;
2   
3   import java.util.List;
4   
5   /***
6    * An <code>ChainedOption</code> is responsible for handling an attribute in a
7    * command object, such as a Struts ActionForm or plain Java Bean, and the
8    * available options for this attribute.
9    * <p />
10   * To fulfil this responsibility, implement the
11   * {@link #retrieveOptions(Object, Object)}method, which should extract any
12   * values that this <code>ChainedOption</code> depends from the command object
13   * and retrieve the available options for these values. Also, implement the
14   * {@link #updateValue(Object, List, Object)}method to check the current value
15   * of the managed attribute against the current list of available options and
16   * optionally update the value if the current one is not present in the list.
17   * <p />
18   * Example: The value object is a Query object of some sort. It has a
19   * <code>region</code> property and a <code>country</code> property. Our
20   * <code>ChainedOption</code> corresponds to the <code>country</code> property
21   * in the query object. The {@link net.sf.chainedoptions.ChainedOptionManager}
22   * managing this <code>ChainedOption</code> decides that a new list of available
23   * countries is needed, perhaps because the <code>region</code> property has
24   * changed. The <code>ChainedOptionManager</code> calls
25   * {@link #retrieveOptions(Object, Object)}method on the
26   * <code>ChainedOption</code>, which knows how to get the countries that match
27   * the current <code>region</code> in the query object.
28   * <p>
29   * The <code>ChainedOptionManager</code> then calls
30   * {@link #updateValue(Object, List, Object)}on the ChainedOption, which knows
31   * how to set the <code>country</code> property of the query object. It takes
32   * the list of available options as a parameter. The <code>updateValue</code>
33   * method checks if the current <code>country</code> value in the query exists
34   * in the list of options. If it exists in the list, nothing needs to be done.
35   * However, if the current value does not exist in the list, the query object
36   * needs a default value. The <code>ChainedOption</code> then calculates a
37   * default value, possibly by calling its
38   * {@link net.sf.chainedoptions.ChainedOptionStrategy}, and the <code>country</code>
39   * property in the query object is set to the default value.
40   * 
41   * @see net.sf.chainedoptions.AbstractChainedOption
42   * @see net.sf.chainedoptions.ChainedOptionManager
43   * @see net.sf.chainedoptions.AbstractChainedOption
44   * 
45   * @author Mattias Arthursson
46   * @author Ulrik Sandberg
47   */
48  public interface ChainedOption {
49      /***
50       * Retrieve a value List for this ChainedOption corresponding to the current
51       * values in the <code>command</code> that this <code>ChainedOption</code>
52       * depends on. This method may use a {@link BeanConverter}to translate Java
53       * Beans to {@link LabelValueBean}objects and an
54       * {@link ChainedOptionStrategy}to perform additional modifications to the
55       * option list.
56       * 
57       * @param command
58       *            Command object to use when extracting values that the
59       *            <code>ChainedOption</code> depends on.
60       * @param context
61       *            may contain any context that might be interesting for
62       *            retreiving valid options. E.g. a
63       *            <code>HttpServletRequest</code> object can be supplied as
64       *            context for a Strategy to perform filtering based on user
65       *            access.
66       * 
67       * @return A list of {@link LabelValueBean}objects.
68       */
69      List retrieveOptions(Object command, Object context);
70  
71      /***
72       * Check the <code>command</code> if it needs to be updated. The
73       * <code>options</code> list may be used for choosing a default value.
74       * 
75       * @param command
76       *            The command object that may be updated.
77       * @param options
78       *            A list of {@link LabelValueBean}objects to choose from.
79       * @param context
80       *            may contain any context that might be interesting for
81       *            retreiving valid options. E.g. a
82       *            <code>HttpServletRequest</code> object can be supplied as
83       *            context for a Strategy to perform filtering based on user
84       *            access.
85       */
86      void updateValue(Object command, List options, Object context);
87  
88      /***
89       * Get the key that identifies the list of options corresponding to this
90       * <code>ChainedOption</code>.
91       * 
92       * @return the key as a String.
93       */
94      String getOptionsKey();
95  
96      /***
97       * Get the {@link ChainedOptionStrategy}to use for filtering and sorting
98       * values as well as for selecting the default value.
99       * 
100      * @param command
101      *            the command to use for selecting the correct Strategy.
102      * 
103      * @return the <code>ChainedOptionStrategy</code> to use based on the
104      *         current situation. Some implementations may have several
105      *         strategies to choose from, and this method is responsible for
106      *         choosing the correct one in each situation based on the current
107      *         values in the <code>command</code>.
108      */
109     ChainedOptionStrategy getStrategy(Object command);
110 }