    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.beanutils;
    018
    019import java.beans.PropertyDescriptor;
    020import java.util.Set;
    021
    022/**
    023 * <p>
    024 * A context interface used during introspection for querying and setting
    025 * property descriptors.
    026 * </p>
    027 * <p>
    028 * An implementation of this interface is passed to {@link BeanIntrospector}
    029 * objects during processing of a bean class. It allows the
    030 * {@code BeanIntrospector} to deliver descriptors for properties it has
    031 * detected. It is also possible to find out which properties have already been
    032 * found by another {@code BeanIntrospector}; this allows multiple
    033 * {@code BeanIntrospector} instances to collaborate.
    034 * </p>
    035 *
    036 * @since 1.9
    037 */
    038public interface IntrospectionContext {
    039    /**
    040     * Adds the given property descriptor to this context. This method is called
    041     * by a {@code BeanIntrospector} during introspection for each detected
    042     * property. If this context already contains a descriptor for the affected
    043     * property, it is overridden.
    044     *
    045     * @param desc the property descriptor
    046     */
    047    void addPropertyDescriptor(PropertyDescriptor desc);
    048
    049    /**
    050     * Adds an array of property descriptors to this context. Using this method
    051     * multiple descriptors can be added at once.
    052     *
    053     * @param descriptors the array of descriptors to be added
    054     */
    055    void addPropertyDescriptors(PropertyDescriptor[] descriptors);
    056
    057    /**
    058     * Returns the descriptor for the property with the given name or
    059     * <strong>null</strong> if this property is unknown.
    060     *
    061     * @param name the name of the property in question
    062     * @return the descriptor for this property or <strong>null</strong> if this property
    063     *         is unknown
    064     */
    065    PropertyDescriptor getPropertyDescriptor(String name);
    066
    067    /**
    068     * Returns the class that is subject of introspection.
    069     *
    070     * @return the current class
    071     */
    072    Class<?> getTargetClass();
    073
    074    /**
    075     * Tests whether a descriptor for the property with the given name is
    076     * already contained in this context. This method can be used for instance
    077     * to prevent that an already existing property descriptor is overridden.
    078     *
    079     * @param name the name of the property in question
    080     * @return <strong>true</strong> if a descriptor for this property has already been
    081     *         added, <strong>false</strong> otherwise
    082     */
    083    boolean hasProperty(String name);
    084
    085    /**
    086     * Returns a set with the names of all properties known to this context.
    087     *
    088     * @return a set with the known property names
    089     */
    090    Set<String> propertyNames();
    091
    092    /**
    093     * Removes the descriptor for the property with the given name.
    094     *
    095     * @param name the name of the affected property
    096     */
    097    void removePropertyDescriptor(String name);
    098}