001    // Copyright 2006, 2010 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    /**
018     * A wrapper around the JavaBean Introspector that allows more manageable access to JavaBean properties of objects.
019     * <p/>
020     * Only provides access to <em>simple</em> properties. Indexed properties are ignored.
021     * <p>
022     * Starting in Tapestry 5.2, public fields can now be accessed as if they were properly JavaBean properties. Where there
023     * is a name conflict, the true property will be favored over the field access.
024     */
025    public interface PropertyAccess
026    {
027        /**
028         * Reads the value of a property.
029         * 
030         * @throws UnsupportedOperationException
031         *             if the property is write only
032         * @throws IllegalArgumentException
033         *             if property does not exist
034         */
035        Object get(Object instance, String propertyName);
036    
037        /**
038         * Updates the value of a property.
039         * 
040         * @throws UnsupportedOperationException
041         *             if the property is read only
042         * @throws IllegalArgumentException
043         *             if property does not exist
044         */
045        void set(Object instance, String propertyName, Object value);
046    
047        /**
048         * Returns the adapter for a particular object instance. A convienience over invoking {@link #getAdapter(Class)}.
049         */
050        ClassPropertyAdapter getAdapter(Object instance);
051    
052        /**
053         * Returns the adapter used to access properties within the indicated class.
054         */
055        ClassPropertyAdapter getAdapter(Class forClass);
056    
057        /**
058         * Discards all stored property access information, discarding all created class adapters.
059         */
060        void clearCache();
061    }