1 /*
2 * Copyright 2001-2013 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of 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,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.beans;
17
18 /**
19 * A property that is linked to a specific bean.
20 * <p>
21 * For a JavaBean, this will ultimately wrap a get/set method pair.
22 * Alternate implementations may perform any logic to obtain the value.
23 *
24 * @param <P> the type of the property content
25 * @author Stephen Colebourne
26 */
27 public interface Property<P> {
28
29 /**
30 * Gets the bean which owns this property.
31 * <p>
32 * Each property is fully owned by a single bean.
33 *
34 * @param <B> the bean type
35 * @return the bean, not null
36 */
37 <B extends Bean> B bean();
38
39 /**
40 * Gets the meta-property representing the parts of the property that are
41 * common across all instances, such as the name.
42 *
43 * @return the meta-property, not null
44 */
45 MetaProperty<P> metaProperty();
46
47 /**
48 * Gets the property name.
49 * <p>
50 * The JavaBean style methods getFoo() and setFoo() will lead to a property
51 * name of 'foo' and so on.
52 *
53 * @return the name of the property, not empty
54 */
55 String name();
56
57 //-----------------------------------------------------------------------
58 /**
59 * Gets the value of the property for the associated bean.
60 * <p>
61 * For a JavaBean, this is the equivalent to calling <code>getFoo()</code> on the bean itself.
62 * Alternate implementations may perform any logic to obtain the value.
63 *
64 * @return the value of the property on the bound bean, may be null
65 * @throws UnsupportedOperationException if the property is write-only
66 */
67 P get();
68
69 /**
70 * Sets the value of the property on the associated bean.
71 * <p>
72 * The value must be of the correct type for the property.
73 * See the meta-property for string conversion.
74 * For a standard JavaBean, this is equivalent to calling <code>setFoo()</code> on the bean.
75 * Alternate implementations may perform any logic to change the value.
76 *
77 * @param value the value to set into the property on the bean
78 * @throws ClassCastException if the value is of an invalid type for the property
79 * @throws UnsupportedOperationException if the property is read-only
80 * @throws RuntimeException if the value is rejected by the property (use appropriate subclasses)
81 */
82 void set(Object value);
83
84 /**
85 * Sets the value of the property on the associated bean and returns the previous value.
86 * <p>
87 * This is a combination of the {@code get} and {@code set} methods that matches the definition
88 * of {@code put} in a {@code Map}.
89 *
90 * @param value the value to set into the property on the bean
91 * @return the old value of the property, may be null
92 * @throws ClassCastException if the value is of an invalid type for the property
93 * @throws UnsupportedOperationException if the property is read-only
94 * @throws RuntimeException if the value is rejected by the property (use appropriate subclasses)
95 */
96 P put(Object value);
97
98 //-----------------------------------------------------------------------
99 /**
100 * Checks if this property equals another.
101 * <p>
102 * This compares the meta-property and value.
103 * It does not consider the property or bean types.
104 *
105 * @param obj the other property, null returns false
106 * @return true if equal
107 */
108 @Override
109 boolean equals(Object obj);
110
111 /**
112 * Returns a suitable hash code.
113 *
114 * @return the hash code
115 */
116 @Override
117 int hashCode();
118
119 }