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 * <h5 class='section'>See Also:</h5><ul>
049
050 * </ul>
051 */
052public class BeanMapEntry implements Map.Entry<String,Object> {
053   private final BeanMap<?> beanMap;
054   private final BeanPropertyMeta meta;
055   private final String pName;
056
057   /**
058    * Constructor.
059    *
060    * @param beanMap The bean map that this entry belongs to.
061    * @param property The bean property.
062    * @param pName The bean property name.
063    */
064   protected BeanMapEntry(BeanMap<?> beanMap, BeanPropertyMeta property, String pName) {
065      this.beanMap = beanMap;
066      this.meta = property;
067      this.pName = pName;
068   }
069
070   @Override /* Map.Entry */
071   public String getKey() {
072      return meta.getName();
073   }
074
075   /**
076    * Returns the value of this property.
077    *
078    * <p>
079    * If there is a {@link ObjectSwap} associated with this bean property or bean property type class, then this method
080    * will return the transformed value.
081    * For example, if the bean property type class is a {@link Date} and the bean property has the
082    * {@link org.apache.juneau.swaps.TemporalDateSwap.IsoInstant} swap associated with it through the
083    * {@link Swap#value() @Swap(value)} annotation, this method will return a String containing an
084    * ISO8601 date-time string value.
085    */
086   @Override /* Map.Entry */
087   public Object getValue() {
088      return meta.get(this.beanMap, pName);
089   }
090
091   /**
092    * Sets the value of this property.
093    *
094    * <p>
095    * If the property is an array of type {@code X}, then the value can be a {@code Collection<X>} or {@code X[]} or
096    * {@code Object[]}.
097    *
098    * <p>
099    * If the property is a bean type {@code X}, then the value can either be an {@code X} or a {@code Map}.
100    *
101    * <p>
102    * If there is a {@link ObjectSwap} associated with this bean property or bean property type class, then you must pass
103    * in a transformed value.
104    * For example, if the bean property type class is a {@link Date} and the bean property has the
105    * {@link org.apache.juneau.swaps.TemporalDateSwap.IsoInstant} swap associated with it through the
106    * {@link Swap#value() @Swap(value)} annotation, the value being passed in must be a String
107    * containing an ISO8601 date-time string value.
108    *
109    * @return  The set value after it's been converted.
110    */
111   @Override /* Map.Entry */
112   public Object setValue(Object value) {
113      return meta.set(this.beanMap, pName, value);
114   }
115
116   /**
117    * Returns the bean map that contains this property.
118    *
119    * @return The bean map that contains this property.
120    */
121   public BeanMap<?> getBeanMap() {
122      return this.beanMap;
123   }
124
125   /**
126    * Returns the metadata about this bean property.
127    *
128    * @return Metadata about this bean property.
129    */
130   public BeanPropertyMeta getMeta() {
131      return this.meta;
132   }
133
134   @Override /* Object */
135   public String toString() {
136      return this.getKey() + "=" + this.getValue();
137   }
138}