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
015package org.apache.tapestry5.ioc.services;
016
017import org.apache.tapestry5.ioc.AnnotationProvider;
018
019import java.lang.reflect.Field;
020import 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")
032public 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}