View Javadoc

1   /*
2    * Copyright 2004-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package net.sf.morph.wrap;
17  
18  
19  /**
20   * A wrapper around 'bean-like' structures. Examples of 'bean-like' structures
21   * include a java.lang.Object, a java.util.Map, or any other class that
22   * logically has a set of properties that can be manipulated by name.
23   * 
24   * @author Matt Sgarlata
25   * @since Jan 16, 2005
26   */
27  public interface Bean extends Wrapper, Sizable {
28  
29  	/**
30  	 * Gets the names of the properties which are currently defined for this
31  	 * bean. Note that some beans (e.g. - Maps) allow the creation of new
32  	 * properties, which means isWriteable may return true for property names
33  	 * that are not included in the return value of this method.
34  	 * 
35  	 * @return the names of the properties which are currently defined for this
36  	 *         bean. Note that some beans (e.g. - Maps) allow the creation of
37  	 *         new properties, which means isWriteable may return true for
38  	 *         property names that are not included in the return value of this
39  	 *         method.
40  	 */
41  	public String[] getPropertyNames();
42  
43  	/**
44  	 * Specifies the least restrictive type that may be assigned to the given
45  	 * property. In the case of a weakly typed bean, the correct value to return
46  	 * is simply <code>Object.class</code>, which indicates that any type can
47  	 * be assigned to the given property.
48  	 * 
49  	 * @param propertyName
50  	 *            the name of the property
51  	 * @return the least restrictive type that may be assigned to the given
52  	 *         property. In the case of a weakly typed bean, the correct value
53  	 *         to return is simply <code>Object.class</code>, which indicates
54  	 *         that any type can be assigned to the given property
55  	 * @throws WrapperException
56  	 *             if <code>getPropertyNames</code> returns <code>null</code>
57  	 *             or if the type could not be retrieved for some reason
58  	 */
59  	public Class getType(String propertyName) throws WrapperException;
60  
61  	/**
62  	 * Specifies whether the given property is readable. A reflector can always
63  	 * determine if a property is readable by attempting to read the property
64  	 * value, so this method can be counted on to truly indicate whether or not
65  	 * the given property is readable.
66  	 * 
67  	 * @param propertyName
68  	 *            the name of the property
69  	 * @return <code>true</code> if the property is readable, or <br>
70  	 *         <code>false</code>, otherwise
71  	 * @throws WrapperException
72  	 *             if <code>getPropertyNames</code> returns <code>null</code>
73  	 *             or if the readability of the property cannot be determined
74  	 */
75  	public boolean isReadable(String propertyName) throws WrapperException;
76  
77  	/**
78  	 * Specifies whether the given property is writeable. If it is not possible
79  	 * to determine whether the given property is writeable, this method may
80  	 * simply return <code>true</code>. This method only guarantees that if
81  	 * <code>isWriteable</code> returns false, the method is not writeable.
82  	 * The method may or may not be writeable if this method returns
83  	 * <code>true</code>.
84  	 * 
85  	 * @param propertyName
86  	 *            the name of the property
87  	 * @return <code>false</code> if the property is not writeable or <br>
88  	 *         <code>true</code> if the property is writeable or if this
89  	 *         reflector cannot determine for sure whether or not the property
90  	 *         is writeable
91  	 * @throws WrapperException
92  	 *             if <code>getPropertyNames</code> returns <code>null</code>
93  	 *             or if the writeability of the property cannot be determined
94  	 */
95  	public boolean isWriteable(String propertyName)
96  		throws WrapperException;
97  
98  	/**
99  	 * Retrieves the value of the given property.
100 	 * 
101 	 * @param propertyName
102 	 *            the name of the property
103 	 * @return the property's value
104 	 * @throws WrapperException
105 	 *             if <code>getPropertyNames</code> returns <code>null</code>
106 	 *             or if the value of the property cannot be determined
107 	 */
108 	public Object get(String propertyName) throws WrapperException;
109 
110 	/**
111 	 * Sets the value of the given property.
112 	 * 
113 	 * @param propertyName
114 	 *            the name of the property
115 	 * @param propertyValue
116 	 *            the value to assign to the given property
117 	 * @throws WrapperException
118 	 *             if <code>getPropertyNames</code> returns <code>null</code>
119 	 *             or if the property cannot be set for some other reason (e.g.
120 	 *             because <code>propertyValue</code> is of the wrong type)
121 	 */
122 	public void set(String propertyName, Object propertyValue)
123 		throws WrapperException;
124 
125 }