001// Copyright 2006, 2010, 2013 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 java.lang.annotation.Annotation; 018 019/** 020 * A wrapper around the JavaBean Introspector that allows more manageable access to JavaBean properties of objects. 021 * <p/> 022 * Only provides access to <em>simple</em> properties. Indexed properties are ignored. 023 * <p> 024 * Starting in Tapestry 5.2, public fields can now be accessed as if they were properly JavaBean properties. Where there 025 * is a name conflict, the true property will be favored over the field access. 026 */ 027public interface PropertyAccess 028{ 029 /** 030 * Reads the value of a property. 031 * 032 * @throws UnsupportedOperationException 033 * if the property is write only 034 * @throws IllegalArgumentException 035 * if property does not exist 036 */ 037 Object get(Object instance, String propertyName); 038 039 /** 040 * Updates the value of a property. 041 * 042 * @throws UnsupportedOperationException 043 * if the property is read only 044 * @throws IllegalArgumentException 045 * if property does not exist 046 */ 047 void set(Object instance, String propertyName, Object value); 048 049 /** 050 * Returns the annotation of a given property for the specified type if such an annotation is present, else null. 051 * A convenience over invoking {@link #getAdapter(Object)}.{@link ClassPropertyAdapter#getPropertyAdapter(String)}.{@link PropertyAdapter#getAnnotation(Class)} 052 * 053 * @param instance the object to read a value from 054 * @param propertyName the name of the property to read (case is ignored) 055 * @param annotationClass the type of annotation to return 056 * @throws IllegalArgumentException 057 * if property does not exist 058 * 059 * @since 5.4 060 */ 061 Annotation getAnnotation(Object instance, String propertyName, Class<? extends Annotation> annotationClass); 062 063 /** 064 * Returns the adapter for a particular object instance. A convienience over invoking {@link #getAdapter(Class)}. 065 */ 066 ClassPropertyAdapter getAdapter(Object instance); 067 068 /** 069 * Returns the adapter used to access properties within the indicated class. 070 */ 071 ClassPropertyAdapter getAdapter(Class forClass); 072 073 /** 074 * Discards all stored property access information, discarding all created class adapters. 075 */ 076 void clearCache(); 077}