1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.commons.beanutils.expression;
18
19 /***
20 * Property Name Expression Resolver.
21 * <p>
22 * Methods such as PropertyUtilsBean's <code>setNestedProperty()</code> method
23 * use a <code>Resolver</code> to process a <i>property name</i>
24 * expression and resolve <i>nested</i>, <i>indexed</i> and <i>mapped</i>
25 * property names. The following code provides an example usage
26 * demonstrating all the methods:
27 *
28 * <pre>
29 * // Iterate through a nested property expression
30 * while (resolver.hasNested(name)) {
31 *
32 * // isolate a single property from a nested expresion
33 * String next = resolver.next(name);
34 *
35 * // Process...
36 * String property = resolver.getProperty(next);
37 * if (resolver.isIndexed(next)) {
38 *
39 * int index = resolver.getIndex(next);
40 * bean = getIndexedProperty(bean, property, index);
41 *
42 * } else if (resolver.isMapped(next)) {
43 *
44 * String key = resolver.getKey(next);
45 * bean = getMappedProperty(bean, property, key);
46 *
47 * } else {
48 *
49 * bean = getSimpleProperty(bean, property);
50 *
51 * }
52 *
53 * // remove the processed property from the expression
54 * name = resolver.remove(name);
55 * }
56 * </pre>
57 *
58 * In order to create an implementation, it is important to understand how
59 * BeanUtils/PropertyUtils uses the <code>resolver</code>. The following are
60 * the main methods that use it:
61 * <ul>
62 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean}</li>
63 * <ul>
64 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getIndexedProperty(Object, String)}</li>
65 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getMappedProperty(Object, String)}</li>
66 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getNestedProperty(Object, String)}</li>
67 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getPropertyDescriptor(Object, String)}</li>
68 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#getSimpleProperty(Object, String)}</li>
69 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setIndexedProperty(Object, String, Object)}</li>
70 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setMappedProperty(Object, String, Object)}</li>
71 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setNestedProperty(Object, String, Object)}</li>
72 * <li>{@link org.apache.commons.beanutils.PropertyUtilsBean#setSimpleProperty(Object, String, Object)}</li>
73 * </ul>
74 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean}</li>
75 * <ul>
76 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#copyProperty(Object, String, Object)}</li>
77 * <li>{@link org.apache.commons.beanutils.BeanUtilsBean#setProperty(Object, String, Object)}</li>
78 * </ul>
79 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean}</li>
80 * <ul>
81 * <li>{@link org.apache.commons.beanutils.locale.LocaleBeanUtilsBean#setProperty(Object,
82 * String, Object, String)}</li>
83 * </ul>
84 * </ul>
85 *
86 * @version $Revision: 555845 $ $Date: 2007-07-13 03:52:05 +0100 (Fri, 13 Jul 2007) $
87 * @see org.apache.commons.beanutils.PropertyUtilsBean#setResolver(Resolver)
88 * @since 1.8.0
89 */
90 public interface Resolver {
91
92 /***
93 * Extract the index value from the property expression or -1.
94 *
95 * @param expression The property expression
96 * @return The index value or -1 if the property is not indexed
97 * @throws IllegalArgumentException If the indexed property is illegally
98 * formed or has an invalid (non-numeric) value
99 */
100 int getIndex(String expression);
101
102 /***
103 * Extract the map key from the property expression or <code>null</code>.
104 *
105 * @param expression The property expression
106 * @return The index value
107 * @throws IllegalArgumentException If the mapped property is illegally formed
108 */
109 String getKey(String expression);
110
111 /***
112 * Return the property name from the property expression.
113 *
114 * @param expression The property expression
115 * @return The property name
116 */
117 String getProperty(String expression);
118
119 /***
120 * Indicates whether or not the expression
121 * contains nested property expressions or not.
122 *
123 * @param expression The property expression
124 * @return The next property expression
125 */
126 boolean hasNested(String expression);
127
128 /***
129 * Indicate whether the expression is for an indexed property or not.
130 *
131 * @param expression The property expression
132 * @return <code>true</code> if the expresion is indexed,
133 * otherwise <code>false</code>
134 */
135 boolean isIndexed(String expression);
136
137 /***
138 * Indicate whether the expression is for a mapped property or not.
139 *
140 * @param expression The property expression
141 * @return <code>true</code> if the expresion is mapped,
142 * otherwise <code>false</code>
143 */
144 boolean isMapped(String expression);
145
146 /***
147 * Extract the next property expression from the
148 * current expression.
149 *
150 * @param expression The property expression
151 * @return The next property expression
152 */
153 String next(String expression);
154
155 /***
156 * Remove the last property expresson from the
157 * current expression.
158 *
159 * @param expression The property expression
160 * @return The new expression value, with first property
161 * expression removed - null if there are no more expressions
162 */
163 String remove(String expression);
164
165 }