001    // Copyright 2006, 2008 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.Method;
020    
021    /**
022     * Provides access to a single property within a class. Acts as an {@link org.apache.tapestry5.ioc.AnnotationProvider};
023     * when searching for annotations, the read method (if present) is checked first, followed by the write method, followed
024     * by the underlying field (when the property name matches the field name).
025     *
026     * @see org.apache.tapestry5.ioc.services.ClassPropertyAdapter
027     */
028    public interface PropertyAdapter extends AnnotationProvider
029    {
030        /**
031         * Returns the name of the property.
032         */
033        String getName();
034    
035        /**
036         * Returns true if the property is readable (i.e., has a getter method).
037         */
038        boolean isRead();
039    
040        /**
041         * Returns the method used to read the property, or null if the property is not readable.
042         */
043        public Method getReadMethod();
044    
045        /**
046         * Returns true if the property is writeable (i.e., has a setter method).
047         */
048        boolean isUpdate();
049    
050        /**
051         * Returns the method used to update the property, or null if the property is not writeable.
052         */
053        public Method getWriteMethod();
054    
055        /**
056         * Reads the property value.
057         *
058         * @param instance to read from
059         * @throws UnsupportedOperationException if the property is write only
060         */
061        Object get(Object instance);
062    
063        /**
064         * Updates the property value. The provided value must not be null if the property type is primitive, and must
065         * otherwise be of the proper type.
066         *
067         * @param instance to update
068         * @param value    new value for the property
069         * @throws UnsupportedOperationException if the property is read only
070         */
071        void set(Object instance, Object value);
072    
073        /**
074         * Returns the type of the property.
075         */
076        Class getType();
077    
078        /**
079         * Returns true if the return type of the read method is not the same as the property type. This can occur when the
080         * property has been defined using generics, in which case, the method's type may be Object when the property type
081         * is something more specific. This method is primarily used when generating runtime code related to the property.
082         */
083        boolean isCastRequired();
084    
085    
086        /**
087         * Returns the {@link org.apache.tapestry5.ioc.services.ClassPropertyAdapter} that provides access to other
088         * properties defined by the same class.
089         */
090        ClassPropertyAdapter getClassAdapter();
091    
092        /**
093         * Returns the type of bean to which this property belongs.  This is the same as {@link
094         * org.apache.tapestry5.ioc.services.ClassPropertyAdapter#getBeanType()}.
095         */
096        Class getBeanType();
097    }