001 // Copyright 2006, 2008, 2010, 2011 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry5.ioc.services;
016
017 import org.apache.tapestry5.ioc.AnnotationProvider;
018
019 import java.lang.reflect.Field;
020 import java.lang.reflect.Method;
021
022 /**
023 * Provides access to a single property within a class. Acts as an {@link org.apache.tapestry5.ioc.AnnotationProvider};
024 * when searching for annotations, the read method (if present) is checked first, followed by the write method, followed
025 * by the underlying field (when the property name matches the field name).
026 * <p/>
027 * Starting in release 5.2, this property may actually be a public field. In 5.3, it may be a public static field.
028 *
029 * @see org.apache.tapestry5.ioc.services.ClassPropertyAdapter
030 */
031 @SuppressWarnings("unchecked")
032 public interface PropertyAdapter extends AnnotationProvider
033 {
034 /**
035 * Returns the name of the property (or public field).
036 */
037 String getName();
038
039 /**
040 * Returns true if the property is readable (i.e., has a getter method or is a public field).
041 */
042 boolean isRead();
043
044 /**
045 * Returns the method used to read the property, or null if the property is not readable (or is a public field).
046 */
047 public Method getReadMethod();
048
049 /**
050 * Returns true if the property is writeable (i.e., has a setter method or is a non-final field).
051 */
052 boolean isUpdate();
053
054 /**
055 * Returns the method used to update the property, or null if the property is not writeable (or a public field).
056 */
057 public Method getWriteMethod();
058
059 /**
060 * Reads the property value.
061 *
062 * @param instance to read from
063 * @throws UnsupportedOperationException if the property is write only
064 */
065 Object get(Object instance);
066
067 /**
068 * Updates the property value. The provided value must not be null if the property type is primitive, and must
069 * otherwise be of the proper type.
070 *
071 * @param instance to update
072 * @param value new value for the property
073 * @throws UnsupportedOperationException if the property is read only
074 */
075 void set(Object instance, Object value);
076
077 /**
078 * Returns the type of the property.
079 */
080 Class getType();
081
082 /**
083 * Returns true if the return type of the read method is not the same as the property type. This can occur when the
084 * property has been defined using generics, in which case, the method's type may be Object when the property type
085 * is something more specific. This method is primarily used when generating runtime code related to the property.
086 */
087 boolean isCastRequired();
088
089 /**
090 * Returns the {@link org.apache.tapestry5.ioc.services.ClassPropertyAdapter} that provides access to other
091 * properties defined by the same class.
092 */
093 ClassPropertyAdapter getClassAdapter();
094
095 /**
096 * Returns the type of bean to which this property belongs. This is the same as
097 * {@link org.apache.tapestry5.ioc.services.ClassPropertyAdapter#getBeanType()}.
098 */
099 Class getBeanType();
100
101 /**
102 * Returns true if the property is actually a public field (possibly, a public static field).
103 *
104 * @since 5.2
105 */
106 boolean isField();
107
108 /**
109 * Returns the field if the property is a public field or null if the property is accessed via the read method.
110 *
111 * @since 5.2
112 */
113 Field getField();
114
115 /**
116 * The class in which the property (or public field) is defined.
117 *
118 * @since 5.2
119 */
120 Class getDeclaringClass();
121 }