001// Copyright 2006, 2007, 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 java.lang.annotation.Annotation;
018import java.util.List;
019
020/**
021 * Organizes all {@link org.apache.tapestry5.ioc.services.PropertyAdapter}s for a particular class.
022 * <p/>
023 * Only provides access to <em>simple</em> properties. Indexed properties are ignored.
024 * <p/>
025 * When accessing properties by name, the case of the name is ignored.
026 */
027public interface ClassPropertyAdapter
028{
029    /**
030     * Returns the names of all properties, sorted into alphabetic order. This includes true properties
031     * (as defined in the JavaBeans specification), but also public fields. Starting in Tapestry 5.3, even public static fields are included.
032     */
033    List<String> getPropertyNames();
034
035    /**
036     * Returns the type of bean this adapter provides properties for.
037     */
038    Class getBeanType();
039
040    /**
041     * Returns the property adapter with the given name, or null if no such adapter exists.
042     *
043     * @param name of the property (case is ignored)
044     */
045    PropertyAdapter getPropertyAdapter(String name);
046
047    /**
048     * Reads the value of a property.
049     *
050     * @param instance     the object to read a value from
051     * @param propertyName the name of the property to read (case is ignored)
052     * @throws UnsupportedOperationException if the property is write only
053     * @throws IllegalArgumentException      if property does not exist
054     */
055    Object get(Object instance, String propertyName);
056
057    /**
058     * Updates the value of a property.
059     *
060     * @param instance     the object to update
061     * @param propertyName the name of the property to update (case is ignored)
062     * @throws UnsupportedOperationException if the property is read only
063     * @throws IllegalArgumentException      if property does not exist
064     */
065    void set(Object instance, String propertyName, Object value);
066
067    /**
068     * Returns the annotation of a given property for the specified type if such an annotation is present, else null.
069     *
070     * @param instance     the object to read a value from
071     * @param propertyName the name of the property to read (case is ignored)
072     * @param annotationClass the type of annotation to return
073     *
074     * @throws IllegalArgumentException      if property does not exist
075     *
076     * @since 5.4
077     */
078    Annotation getAnnotation(Object instance, String propertyName, Class<? extends Annotation> annotationClass);
079}