001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  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 distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau;
014
015import java.util.*;
016
017import org.apache.juneau.annotation.*;
018import org.apache.juneau.swap.*;
019
020/**
021 * Represents a single entry in a bean map.
022 *
023 * <p>
024 * This class can be used to get and set property values on a bean, or to get metadata on a property.
025 *
026 * <h5 class='section'>Example:</h5>
027 * <p class='bjava'>
028 *    <jc>// Construct a new bean</jc>
029 *    Person <jv>person</jv> = <jk>new</jk> Person();
030 *
031 *    <jc>// Wrap it in a bean map</jc>
032 *    BeanMap&lt;Person&gt; <jv>beanMap</jv> = BeanContext.<jsf>DEFAULT</jsf>.toBeanMap(<jv>person</jv>);
033 *
034 *    <jc>// Get a reference to the birthDate property</jc>
035 *    BeanMapEntry <jv>birthDate</jv> = <jv>beanMap</jv>.getProperty(<js>"birthDate"</js>);
036 *
037 *    <jc>// Set the property value</jc>
038 *    <jv>birthDate</jv>.setValue(<jk>new</jk> Date(1, 2, 3, 4, 5, 6));
039 *
040 *    <jc>// Or if the DateSwap.DEFAULT_ISO8601DT is registered with the bean context, set a transformed value</jc>
041 *    <jv>birthDate</jv>.setValue(<js>"'1901-03-03T04:05:06-5000'"</js>);
042 * </p>
043 *
044 * <h5 class='section'>See Also:</h5><ul>
045
046 * </ul>
047 */
048public class BeanMapEntry implements Map.Entry<String,Object> {
049   private final BeanMap<?> beanMap;
050   private final BeanPropertyMeta meta;
051   private final String pName;
052
053   /**
054    * Constructor.
055    *
056    * @param beanMap The bean map that this entry belongs to.
057    * @param property The bean property.
058    * @param pName The bean property name.
059    */
060   protected BeanMapEntry(BeanMap<?> beanMap, BeanPropertyMeta property, String pName) {
061      this.beanMap = beanMap;
062      this.meta = property;
063      this.pName = pName;
064   }
065
066   @Override /* Map.Entry */
067   public String getKey() {
068      return meta.getName();
069   }
070
071   /**
072    * Returns the value of this property.
073    *
074    * <p>
075    * If there is a {@link ObjectSwap} associated with this bean property or bean property type class, then this method
076    * will return the transformed value.
077    * For example, if the bean property type class is a {@link Date} and the bean property has the
078    * {@link org.apache.juneau.swaps.TemporalDateSwap.IsoInstant} swap associated with it through the
079    * {@link Swap#value() @Swap(value)} annotation, this method will return a String containing an
080    * ISO8601 date-time string value.
081    */
082   @Override /* Map.Entry */
083   public Object getValue() {
084      return meta.get(this.beanMap, pName);
085   }
086
087   /**
088    * Sets the value of this property.
089    *
090    * <p>
091    * If the property is an array of type {@code X}, then the value can be a {@code Collection<X>} or {@code X[]} or
092    * {@code Object[]}.
093    *
094    * <p>
095    * If the property is a bean type {@code X}, then the value can either be an {@code X} or a {@code Map}.
096    *
097    * <p>
098    * If there is a {@link ObjectSwap} associated with this bean property or bean property type class, then you must pass
099    * in a transformed value.
100    * For example, if the bean property type class is a {@link Date} and the bean property has the
101    * {@link org.apache.juneau.swaps.TemporalDateSwap.IsoInstant} swap associated with it through the
102    * {@link Swap#value() @Swap(value)} annotation, the value being passed in must be a String
103    * containing an ISO8601 date-time string value.
104    *
105    * @return  The set value after it's been converted.
106    */
107   @Override /* Map.Entry */
108   public Object setValue(Object value) {
109      return meta.set(this.beanMap, pName, value);
110   }
111
112   /**
113    * Returns the bean map that contains this property.
114    *
115    * @return The bean map that contains this property.
116    */
117   public BeanMap<?> getBeanMap() {
118      return this.beanMap;
119   }
120
121   /**
122    * Returns the metadata about this bean property.
123    *
124    * @return Metadata about this bean property.
125    */
126   public BeanPropertyMeta getMeta() {
127      return this.meta;
128   }
129
130   @Override /* Object */
131   public String toString() {
132      return this.getKey() + "=" + this.getValue();
133   }
134}