1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.morph.reflect;
17
18 /**
19 * Exposes information available in 'bean-like' structures. Examples of
20 * 'bean-like' structures include a java.lang.Object, a java.util.Map, or any
21 * other class that logically has a set of properties that can be manipulated by
22 * name.
23 *
24 * @author Matt Sgarlata
25 * @since Nov 6, 2004
26 */
27 public interface BeanReflector extends Reflector, SizableReflector {
28
29 /** implicit "class" property */
30 public static final String IMPLICIT_PROPERTY_CLASS = "class";
31
32 /** implicit "propertyNames" property */
33 public static final String IMPLICIT_PROPERTY_PROPERTY_NAMES = "propertyNames";
34
35 /** implicit "this" property */
36 public static final String IMPLICIT_PROPERTY_THIS = "this";
37
38 /**
39 * Gets the names of the properties which are currently defined for the
40 * given bean. Note that some beans (e.g. - Maps) allow the creation of new
41 * properties, which means isWriteable may return true for property names
42 * that are not included in the return value of this method.
43 *
44 * @param bean
45 * the bean for which we would like a list of properties
46 * @return the names of the properties which are currently defined for the
47 * given bean. Note that some beans (e.g. - Maps) allow the creation
48 * of new properties, which means isWriteable may return true for
49 * property names that are not included in the return value of this
50 * method.
51 * @throws ReflectionException
52 * if bean is <code>null</code>
53 */
54 public String[] getPropertyNames(Object bean) throws ReflectionException;
55
56 /**
57 * Specifies the least restrictive type that may be assigned to the given
58 * property. In the case of a weakly typed bean, the correct value to return
59 * is simply <code>Object.class</code>, which indicates that any type can
60 * be assigned to the given property.
61 *
62 * @param bean
63 * the bean
64 * @param propertyName
65 * the name of the property
66 * @return the least restrictive type that may be assigned to the given
67 * property. In the case of a weakly typed bean, the correct value
68 * to return is simply <code>Object.class</code>, which indicates
69 * that any type can be assigned to the given property
70 * @throws ReflectionException
71 * if <code>bean</code> or <code>propertyName</code> are
72 * <code>null</code> or <br>
73 * this is a strongly typed bean reflector and the given
74 * property does not exist or <br>
75 * if the type could not be retrieved for some reason
76 */
77 public Class getType(Object bean, String propertyName)
78 throws ReflectionException;
79
80 /**
81 * Specifies whether the given property is readable. A reflector can always
82 * determine if a property is readable by attempting to read the property
83 * value, so this method can be counted on to truly indicate whether or not
84 * the given property is readable.
85 *
86 * @param bean
87 * the bean
88 * @param propertyName
89 * the name of the property
90 * @return <code>true</code> if the property is readable, or <br>
91 * <code>false</code>, otherwise
92 * @throws ReflectionException
93 * if <code>bean</code> or <code>propertyName</code> are
94 * <code>null</code> or <br>
95 * if the readability of the property cannot be determined
96 */
97 public boolean isReadable(Object bean, String propertyName)
98 throws ReflectionException;
99
100 /**
101 * Specifies whether the given property is writeable. If the reflector
102 * cannot determine whether the given property is writeable, it may simply
103 * return <code>true</code>. This method only guarantees that if
104 * <code>isWriteable</code> returns false, the method is not writeable.
105 * The method may or may not be writeable if this method returns
106 * <code>true</code>.
107 *
108 * @param bean
109 * the bean
110 * @param propertyName
111 * the name of the property
112 * @return <code>false</code> if the property is not writeable or <br>
113 * <code>true</code> if the property is writeable or if this
114 * reflector cannot determine for sure whether or not the property
115 * is writeable
116 * @throws ReflectionException
117 * if <code>bean</code> or <code>propertyName</code> are
118 * <code>null</code> or <br>
119 * if the writeability of the property cannot be determined
120 */
121 public boolean isWriteable(Object bean, String propertyName)
122 throws ReflectionException;
123
124 /**
125 * Retrieves the value of the given property.
126 *
127 * @param bean
128 * the bean
129 * @param propertyName
130 * the name of the property
131 * @return the property's value
132 * @throws ReflectionException
133 * if <code>bean</code> or <code>propertyName</code> is
134 * <code>null</code> or <br>
135 * if the value of the property cannot be determined or <br>
136 */
137 public Object get(Object bean, String propertyName)
138 throws ReflectionException;
139
140 /**
141 * Sets the value of the given property.
142 *
143 * @param bean
144 * the bean
145 * @param propertyName
146 * the name of the property
147 * @param propertyValue
148 * the value to assign to the given property
149 * @throws ReflectionException
150 * if <code>bean</code> or <code>propertyName</code> are
151 * <code>null</code> or <br>
152 * if the property cannot be set for some other reason (e.g.
153 * because <code>propertyValue</code> is of the wrong type)
154 */
155 public void set(Object bean, String propertyName, Object propertyValue)
156 throws ReflectionException;
157
158 }