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}