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