    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}