    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}