    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 */
    017
    018package org.apache.commons.beanutils2;
    019
    020/**
    021 * <p>
    022 * A <strong>DynaBean</strong> is a Java object that supports properties whose names and data types, as well as values, may be dynamically modified. To the
    023 * maximum degree feasible, other components of the BeanUtils package will recognize such beans and treat them as standard JavaBeans for the purpose of
    024 * retrieving and setting property values.
    025 * </p>
    026 */
    027public interface DynaBean {
    028
    029    /**
    030     * Does the specified mapped property contain a value for the specified key value?
    031     *
    032     * @param name Name of the property to check
    033     * @param key  Name of the key to check
    034     * @return {@code true} if the mapped property contains a value for the specified key, otherwise {@code false}
    035     * @throws IllegalArgumentException if there is no property of the specified name
    036     */
    037    boolean contains(String name, String key);
    038
    039    /**
    040     * Gets the value of a simple property with the specified name.
    041     *
    042     * @param name Name of the property whose value is to be retrieved
    043     * @return The property's value
    044     * @throws IllegalArgumentException if there is no property of the specified name
    045     */
    046    Object get(String name);
    047
    048    /**
    049     * Gets the value of an indexed property with the specified name.
    050     *
    051     * @param name  Name of the property whose value is to be retrieved
    052     * @param index Index of the value to be retrieved
    053     * @return The indexed property's value
    054     * @throws IllegalArgumentException  if there is no property of the specified name
    055     * @throws IllegalArgumentException  if the specified property exists, but is not indexed
    056     * @throws IndexOutOfBoundsException if the specified index is outside the range of the underlying property
    057     * @throws NullPointerException      if no array or List has been initialized for this property
    058     */
    059    Object get(String name, int index);
    060
    061    /**
    062     * Gets the value of a mapped property with the specified name, or {@code null} if there is no value for the specified key.
    063     *
    064     * @param name Name of the property whose value is to be retrieved
    065     * @param key  Key of the value to be retrieved
    066     * @return The mapped property's value
    067     * @throws IllegalArgumentException if there is no property of the specified name
    068     * @throws IllegalArgumentException if the specified property exists, but is not mapped
    069     */
    070    Object get(String name, String key);
    071
    072    /**
    073     * Gets the {@code DynaClass} instance that describes the set of properties available for this DynaBean.
    074     *
    075     * @return The associated DynaClass
    076     */
    077    DynaClass getDynaClass();
    078
    079    /**
    080     * Remove any existing value for the specified key on the specified mapped property.
    081     *
    082     * @param name Name of the property for which a value is to be removed
    083     * @param key  Key of the value to be removed
    084     * @throws IllegalArgumentException if there is no property of the specified name
    085     */
    086    void remove(String name, String key);
    087
    088    /**
    089     * Sets the value of an indexed property with the specified name.
    090     *
    091     * @param name  Name of the property whose value is to be set
    092     * @param index Index of the property to be set
    093     * @param value Value to which this property is to be set
    094     * @throws ConversionException       if the specified value cannot be converted to the type required for this property
    095     * @throws IllegalArgumentException  if there is no property of the specified name
    096     * @throws IllegalArgumentException  if the specified property exists, but is not indexed
    097     * @throws IndexOutOfBoundsException if the specified index is outside the range of the underlying property
    098     */
    099    void set(String name, int index, Object value);
    100
    101    /**
    102     * Sets the value of a simple property with the specified name.
    103     *
    104     * @param name  Name of the property whose value is to be set
    105     * @param value Value to which this property is to be set
    106     * @throws ConversionException      if the specified value cannot be converted to the type required for this property
    107     * @throws IllegalArgumentException if there is no property of the specified name
    108     * @throws NullPointerException     if an attempt is made to set a primitive property to null
    109     */
    110    void set(String name, Object value);
    111
    112    /**
    113     * Sets the value of a mapped property with the specified name.
    114     *
    115     * @param name  Name of the property whose value is to be set
    116     * @param key   Key of the property to be set
    117     * @param value Value to which this property is to be set
    118     * @throws ConversionException      if the specified value cannot be converted to the type required for this property
    119     * @throws IllegalArgumentException if there is no property of the specified name
    120     * @throws IllegalArgumentException if the specified property exists, but is not mapped
    121     */
    122    void set(String name, String key, Object value);
    123
    124}