package org.apache.commons.beanutils2;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import java.util.Map;

/**
 * Provides access to properties and methods of a bean.
 *
 * @param <B> the type of the bean this BeanAcessor is associated with.
 */
public interface BeanAccessor<B>
{

    // get

    /**
     * Gets the value of the property with name {@code propertyName} from the bean wrapped by this BeanAccessor. The
     * value will be wrapped in a {@code BeanAccessor} to enable fluent calls.
     *
     * @param propertyName the name of the property to get the value from. Must not be {@code null}!
     * @return a {@code BeanAccessor} wrapping the properties value.
     */
    BeanAccessor<?> get( String propertyName );

    /**
     * Selects the indexed property with name {@code propertyName} from the bean wrapped by this {@code BeanAccessor}. A
     * {@link IndexedPropertyGetterAccessor} will be returned for specifying the index to return the value of.
     *
     * @param propertyName the name of the indexed property to select. Must not be {@code null}!
     * @return a {@link IndexedPropertyGetterAccessor} for specifying the index to return the value of.
     */
    IndexedPropertyGetterAccessor<?> getIndexed( String propertyName );

    /**
     * Selects the mapped property with name {@code propertyName} from the bean wrapped by this {@code BeanAccessor}. A
     * {@link MappedPropertyGetterAccessor} will be returned for specifying the key to return the value of.
     *
     * @param propertyName the name of the mapped property to select. Must not be {@code null}!
     * @return a {@link MappedPropertyGetterAccessor} for specifying the key to return the value of.
     */
    MappedPropertyGetterAccessor getMapped( String propertyName );

    /**
     * Gets the bean wrapped by this {@code BeanAccessor}.
     *
     * @return the bean.
     */
    B get();

    /**
     * Tries to cast the bean wrapped by this {@code BeanAccessor} an returns the result.
     *
     * @param <V> the type to cast the wrapped bean to.
     * @return the wrapped bean, casted to type {@code V}.
     */
    <V> V cast();

    // set

    /**
     * Selects the property with name {@code propertyName} for setting a new value. A {@link BeanPropertySetter} will be
     * returned for specifying the new value.
     *
     * @param propertyName the name of the property to select for setting a new value. Must not be {@code null}.
     * @return a {@link BeanPropertySetter} for setting a new value.
     */
    BeanPropertySetter<B> set( String propertyName );

    /**
     * Selects the indexed property with name {@code propertyName} for setting a new value. A
     * {@link IndexedPropertySetterAccessor} will be returned for specifying the index to set a new value to.
     *
     * @param propertyName the name of the indexed property to select for setting a new value. Must not be {@code null}.
     * @return a {@link IndexedPropertySetterAccessor} for setting a new value.
     */
    IndexedPropertySetterAccessor<B> setIndexed( String propertyName );

    /**
     * Selects the mapped property with name {@code propertyName} for setting a new value. A
     * {@link MappedPropertySetterAccessor} will be returned for specifying the key to set a new value to.
     *
     * @param propertyName the name of the mapped property to select for setting a new value. Must not be {@code null}.
     * @return a {@link MappedPropertySetterAccessor} for setting a new value.
     */
    MappedPropertySetterAccessor<B> setMapped( String propertyName );

    // clone

    /**
     * Clones a bean based on the available property getters and setters, even if the bean class itself does not
     * implement Cloneable.
     * <p>
     * <strong>Note:</strong> this method creates a <strong>shallow</strong> clone. In other words, any objects referred
     * to by the bean are shared with the clone rather than being cloned in turn.
     *
     * @return the cloned bean
     */
    B cloneBean();

    /**
     * Copies property values from the bean wrapped by this {@code BeanAccessor} to {@code target} for all cases where
     * the property names are the same. For each property, a conversion is attempted as necessary.
     * <p>
     * <strong>Note</strong> that this method is intended to perform a "shallow copy" of the properties and so complex
     * properties (for example, nested ones) will not be copied.
     * <p>
     * <strong>TODO</strong> should we implement something like the following?
     * <p>
     * If you know that no type conversions are required, the <code>copyProperties()</code> method in
     * {@link PropertyUtils} will execute faster than this method.
     * <p>
     * <strong>FIXME</strong> - Indexed and mapped properties that do not have getter and setter methods for the
     * underlying array or Map are not copied by this method.
     *
     * @param <T> the type of the bean to copy properties to.
     * @param target the target to copy properties to from the wrapped bean
     */
    <T extends B> void copyPropertiesTo( T target );

    // description

    /**
     * Return the entire set of properties for which the specified bean provides a read method. This map contains the
     * property names as keys and the property values as values, for all properties the bean provides a read method for
     * (i.e. where the getReadMethod() returns non-null).
     * <p>
     * This map can be fed back to a call to <code>BeanAccessor.populate()</code> to reconstitute the same set of
     * properties, modulo differences for read-only and write-only properties, but only if there are no indexed
     * properties.
     * <p>
     * <strong>Warning:</strong> if any of the bean property implementations contain (directly or indirectly) a call to
     * this method then a stack overflow may result. For example: <code><pre>
     * class MyBean
     * {
     *    public Map&lt;String, Object&gt; getParameterMap()
     *    {
     *         on( this ).describe;
     *    }
     * }
     * </pre></code> will result in an infinite regression when <code>getParametersMap</code> is called. It is
     * recommended that such methods are given alternative names (for example, <code>parametersMap</code>).
     *
     * @return Map that contains the property names as keys and property values as values.
     */
    Map<String, Object> describe();

    /**
     * Populate {@code properties} to the bean wrapped by this {@code BeanAccessor}. The map of properties passed to
     * this method has to specify names of properties to set and corresponding values as key-value-pairs.
     *
     * @param properties Map keyed by property name, with the corresponding value to be set.
     *            Must not be {@code null}.
     */
    void populate( Map<String, Object> properties );

    // methods invocation

    /**
     * Invokes the method with name {@code methodName}. An {@link ArgumentsAccessor} will be returned to specify the
     * parameters for the method invocation.
     *
     * @param methodName the name of the method to invoke. Must not be {@code null}!
     * @return an {@link ArgumentsAccessor} to specify arguments for the method invocation.
     */
    ArgumentsAccessor invoke( String methodName );

    /**
     * Invokes the method with name {@code methodName} and the exact arguments. An {@link ArgumentsAccessor} will be
     * returned to specify the parameters for the method invocation.
     *
     * @param methodName the name of the method to invoke. Must not be {@code null}!
     * @return a {@link ArgumentsAccessor} to specify any arguments
     */
    ArgumentsAccessor invokeExact( String methodName );

}