    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    }