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.transform.*;
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='bcode'>
028 *    <jc>// Construct a new bean</jc>
029 *    Person p = <jk>new</jk> Person();
030 * 
031 *    <jc>// Wrap it in a bean map</jc>
032 *    BeanMap&lt;Person&gt; b = BeanContext.<jsf>DEFAULT</jsf>.forBean(p);
033 * 
034 *    <jc>// Get a reference to the birthDate property</jc>
035 *    BeanMapEntry birthDate = b.getProperty(<js>"birthDate"</js>);
036 * 
037 *    <jc>// Set the property value</jc>
038 *    birthDate.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 *    birthDate.setValue(<js>"'1901-03-03T04:05:06-5000'"</js>);
042 * </p>
043 */
044public class BeanMapEntry implements Map.Entry<String,Object> {
045   private final BeanMap<?> beanMap;
046   private final BeanPropertyMeta meta;
047   private final String pName;
048
049   /**
050    * Constructor.
051    * 
052    * @param beanMap The bean map that this entry belongs to.
053    * @param property The bean property.
054    * @param pName The bean property name.
055    */
056   protected BeanMapEntry(BeanMap<?> beanMap, BeanPropertyMeta property, String pName) {
057      this.beanMap = beanMap;
058      this.meta = property;
059      this.pName = pName;
060   }
061
062   @Override /* Map.Entry */
063   public String getKey() {
064      return meta.getName();
065   }
066
067   /**
068    * Returns the value of this property.
069    * 
070    * <p>
071    * If there is a {@link PojoSwap} associated with this bean property or bean property type class, then this method
072    * will return the transformed value.
073    * For example, if the bean property type class is a {@link Date} and the bean property has the
074    * {@link org.apache.juneau.transforms.DateSwap.ISO8601DT} swap associated with it through the
075    * {@link Swap#value() @Swap.value()} annotation, this method will return a String containing an
076    * ISO8601 date-time string value.
077    */
078   @Override /* Map.Entry */
079   public Object getValue() {
080      return meta.get(this.beanMap, pName);
081   }
082
083   /**
084    * Sets the value of this property.
085    * 
086    * <p>
087    * If the property is an array of type {@code X}, then the value can be a {@code Collection<X>} or {@code X[]} or
088    * {@code Object[]}.
089    * 
090    * <p>
091    * If the property is a bean type {@code X}, then the value can either be an {@code X} or a {@code Map}.
092    * 
093    * <p>
094    * If there is a {@link PojoSwap} associated with this bean property or bean property type class, then you must pass
095    * in a transformed value.
096    * For example, if the bean property type class is a {@link Date} and the bean property has the
097    * {@link org.apache.juneau.transforms.DateSwap.ISO8601DT} swap associated with it through the
098    * {@link Swap#value() @Swap.value()} annotation, the value being passed in must be a String
099    * containing an ISO8601 date-time string value.
100    * 
101    * @return  The set value after it's been converted.
102    */
103   @Override /* Map.Entry */
104   public Object setValue(Object value) {
105      return meta.set(this.beanMap, pName, value);
106   }
107
108   /**
109    * Returns the bean map that contains this property.
110    * 
111    * @return The bean map that contains this property.
112    */
113   public BeanMap<?> getBeanMap() {
114      return this.beanMap;
115   }
116
117   /**
118    * Returns the metadata about this bean property.
119    * 
120    * @return Metadata about this bean property.
121    */
122   public BeanPropertyMeta getMeta() {
123      return this.meta;
124   }
125
126   @Override /* Object */
127   public String toString() {
128      return this.getKey() + "=" + this.getValue();
129   }
130}