All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.jgoodies.binding.beans.BeanAdapter Maven / Gradle / Ivy

Go to download

The JGoodies Binding library connects object properties to Swing user interface components. And it helps you represent the state and behavior of a presentation independently of the GUI components used in the interface.

The newest version!
/*
 * Copyright (c) 2002-2015 JGoodies Software GmbH. All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  o Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 *  o Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 *  o Neither the name of JGoodies Software GmbH nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.jgoodies.binding.beans;

import static com.jgoodies.common.base.Preconditions.checkArgument;
import static com.jgoodies.common.base.Preconditions.checkNotBlank;
import static com.jgoodies.common.internal.Messages.MUST_NOT_BE_BLANK;

import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.beans.PropertyDescriptor;
import java.beans.PropertyVetoException;
import java.lang.reflect.Method;
import java.util.HashMap;
import java.util.Map;

import com.jgoodies.binding.value.AbstractValueModel;
import com.jgoodies.binding.value.ValueHolder;
import com.jgoodies.binding.value.ValueModel;
import com.jgoodies.common.base.Objects;


/**
 * Converts multiple Java Bean properties into ValueModels.
 * The bean properties must be single valued properties as described by the
 * Java
 * Bean Specification. See below for a comparison with the more frequently
 * used PresentationModel class and the rarely used PropertyAdapter.

* * ValueModels can be created for a property name using * {@link #getValueModel(String)} or for a triple of (property name, getter * name, setter name) using {@link #getValueModel(String, String, String)}. * If you just specify the property name, the adapter uses the standard * Java Bean introspection to lookup the available properties and how to * read and write the property value. In case of custom readers and writers * you may specify a custom BeanInfo class, or as a shortcut use the method * that accepts the optional getter and setter name. If these are specified, * introspection will be bypassed and a PropertyDescriptor will be * created for the given property name, getter and setter name. * Note: For each property name subsequent calls * to these methods must use the same getter and setter names. Attempts * to violate this constraint are rejected with an IllegalArgumentException.

* * Property values for a given property name can be read using * {@link #getValue(String)}. To set a value for a for a property name * invoke {@link #setValue(String, Object)}.

* * Optionally the BeanAdapter can observe changes in bound * properties as described in section 7.4 of the Bean specification. * The bean then must provide support for listening on properties as described * in section 7.4 of this specification. * You can enable this feature by setting the constructor parameter * {@code observeChanges} to {@code true}. * If the adapter observes changes, the ValueModels returned by * {@code #getValueModel} will fire value change events, * i.e. PropertyChangeEvents for the property {@code "value"}. * Even if you ignore property changes, you can access the adapted * property value via {@code #getValue()}. * It's just that you won't be notified about changes.

* * In addition you can observe the bean's bound properties * by registering PropertyChangeListeners with the bean using * {@code #addBeanPropertyChangeListener}. These listeners will be removed * from the old bean before the bean changes and will be re-added after * the new bean has been set. Therefore these listeners will be notified * about changes only if the current bean changes a property. They won't be * notified if the bean changes - and in turn the property value. If you want * to observes property changes caused by bean changes too, register with the * adapting ValueModel as returned by {@code #getValueModel(String)}.

* * The BeanAdapter provides two access styles to the target bean * that holds the adapted property: you can specify a bean directly, * or you can use a bean channel to access the bean indirectly. * In the latter case you specify a {@code ValueModel} * that holds the bean that in turn holds the adapted properties.

* * If the adapted bean is {@code null} the BeanAdapter can * neither read nor set a value. In this case {@code #getValue} * returns {@code null} and {@code #setValue} will silently * ignore the new value.

* * This adapter throws three PropertyChangeEvents if the bean changes: * beforeBean, bean and afterBean. This is useful * when sharing a bean channel and you must perform an operation before * or after other listeners handle a bean change. Since you cannot rely * on the order listeners will be notified, only the beforeBean * and afterBean events are guaranteed to be fired before and * after the bean change is fired. * Note that {@code #getBean()} returns the new bean before * any of these three PropertyChangeEvents is fired. Therefore listeners * that handle these events must use the event's old and new value * to determine the old and new bean. * The order of events fired during a bean change is:

    *
  1. this adapter's bean channel fires a value change, *
  2. this adapter fires a beforeBean change, *
  3. this adapter fires the bean change, *
  4. this adapter fires an afterBean change. *

* * Note: * BeanAdapters that observe changes have a PropertyChangeListener * registered with the target bean. Hence, a bean has a reference * to any BeanAdapter that observes it. To avoid memory leaks * it is recommended to remove this listener if the bean lives much longer * than the BeanAdapter, enabling the garbage collector to remove the adapter. * To do so, you can call {@code setBean(null)} or set the * bean channel's value to null. * As an alternative you can use event listener lists in your beans * that implement references with {@code WeakReference}.

* * Setting the bean to null has side-effects, for example the adapter * fires a change event for the bound property bean and other properties. * And the value of ValueModel's vended by this adapter may change. * However, typically this is fine and setting the bean to null * is the first choice for removing the reference from the bean to the adapter. * Another way to clear the reference from the target bean is * to call {@code #release}. It has no side-effects, but the adapter * must not be used anymore once #release has been called.

* * Constraints: If property changes shall be observed, * the bean class must support bound properties, i. e. it must provide * the following pair of methods for registration of multicast property * change event listeners: *

 * public void addPropertyChangeListener(PropertyChangeListener x);
 * public void removePropertyChangeListener(PropertyChangeListener x);
 * 
* * PropertyAdapter vs. BeanAdapter vs. PresentationModel
* Basically the BeanAdapter does for multiple properties what the * {@link com.jgoodies.binding.beans.PropertyAdapter} does for a * single bean property. * If you adapt multiple properties of the same bean, you better use * the BeanAdapter. It registers a single PropertyChangeListener with the bean, * where multiple PropertyAdapters would register multiple listeners. * If you adapt bean properties for an editor, you will typically use the * {@link com.jgoodies.binding.PresentationModel}. The PresentationModel is * more powerful than the BeanAdapter. It adds support for buffered models, * and provides an extensible mechanism for observing the change state * of the bean and related objects.

* * Basic Examples: *

 * // Direct access, ignores changes
 * Address address = new Address()
 * BeanAdapter adapter = new BeanAdapter(address);
 * adapter.setValue("street", "Broadway");
 * System.out.println(address.getStreet());        // Prints "Broadway"
 * address.setStreet("Franz-Josef-Str.");
 * System.out.println(adapter.getValue("street")); // Prints "Franz-Josef-Str."
 *
 *
 * //Direct access, observes changes
 * BeanAdapter adapter = new BeanAdapter(address, true);
 *
 *
 * // Indirect access, ignores changes
 * ValueHolder addressHolder = new ValueHolder(address1);
 * BeanAdapter adapter = new BeanAdapter(addressHolder);
 * adapter.setValue("street", "Broadway");         // Sets the street in address1
 * System.out.println(address1.getStreet());       // Prints "Broadway"
 * adapter.setBean(address2);
 * adapter.setValue("street", "Robert-Koch-Str."); // Sets the street in address2
 * System.out.println(address2.getStreet());       // Prints "Robert-Koch-Str."
 *
 *
 * // Indirect access, observes changes
 * ValueHolder addressHolder = new ValueHolder();
 * BeanAdapter adapter = new BeanAdapter(addressHolder, true);
 * addressHolder.setValue(address1);
 * address1.setStreet("Broadway");
 * System.out.println(adapter.getValue("street")); // Prints "Broadway"
 *
 *
 * // Access through ValueModels
 * Address address = new Address();
 * BeanAdapter adapter = new BeanAdapter(address);
 * ValueModel streetModel = adapter.getValueModel("street");
 * ValueModel cityModel   = adapter.getValueModel("city");
 * streetModel.setValue("Broadway");
 * System.out.println(address.getStreet());        // Prints "Broadway"
 * address.setCity("Hamburg");
 * System.out.println(cityModel.getValue());       // Prints "Hamburg"
 * 
* * Adapter Chain Example: *
Builds an adapter chain from a domain model to the presentation layer. *
 * Country country = new Country();
 * country.setName("Germany");
 * country.setEuMember(true);
 *
 * BeanAdapter countryAdapter = new BeanAdapter(country, true);
 *
 * JTextField nameField = new JTextField();
 * nameField.setDocument(new DocumentAdapter(
 *     countryAdapter.getValueModel("name")));
 *
 * JCheckBox euMemberBox = new JCheckBox("Is EU Member");
 * euMemberBox.setModel(new ToggleButtonAdapter(
 *      countryAdapter.getValueModel("euMember")));
 *
 * // Using factory methods
 * JTextField nameField   = Factory.createTextField(country, "name");
 * JCheckBox  euMemberBox = Factory.createCheckBox (country, "euMember");
 * euMemberBox.setText("Is EU Member");
 * 

* * As of version 1.3 this class is no longer marked as final, * but lacks the documentation for subclass constraints. * I plan to introduce an interface that shall describe the semantics * required by the PresentationModel class. Until then, this BeanAdapter * implementation describes the semantics and all constraints.

* * TODO: Improve the class comment and focus on the main features.

* * TODO: Consider adding a feature to ensure that update notifications * are performed in the event dispatch thread. In case the adapted bean * is changed in a thread other than the event dispatch thread, such * a feature would help complying with Swing's single thread rule. * The feature could be implemented by an extended PropertyChangeSupport.

* * TODO: I plan to improve the support for adapting beans that do not fire * PropertyChangeEvents. This affects the classes PropertyAdapter, BeanAdapter, * and PresentationModel. Basically the PropertyAdapter and the BeanAdapter's * internal SimplePropertyAdapter's shall be able to optionally self-fire * a PropertyChangeEvent in case the bean does not. There are several * downsides with self-firing events compared to bound bean properties. * See Issue * 49 for more information about the downsides.

* * The observeChanges constructor parameter shall be replaced by a more * fine-grained choice to not observe (former observeChanges=false), * to observe bound properties (former observeChanges=true), and a new * setting for self-firing PropertyChangeEvents if a value is set. * The latter case may be further splitted up to specify how the * self-fired PropertyChangeEvent is created: *

    *
  1. oldValue=null, newValue=null *
  2. oldValue=null, newValue=the value set *
  3. oldValue=value read before the set, newValue=the value set *
  4. oldValue=value read before the set, newValue=value read after the set *
* * @author Karsten Lentzsch * @version $Revision: 1.39 $ * * @see com.jgoodies.binding.beans.PropertyAdapter * @see ValueModel * @see ValueModel#getValue() * @see ValueModel#setValue(Object) * @see PropertyChangeEvent * @see PropertyChangeListener * @see java.beans.Introspector * @see java.beans.BeanInfo * @see PropertyDescriptor * * @param the type of the bean managed by this BeanAdapter */ public class BeanAdapter extends Model { // Property Names ********************************************************* /** * The property name used in the PropertyChangeEvent that is fired * before the bean property fires its PropertyChangeEvent. * Useful to perform an operation before listeners that handle the * bean change are notified. See also the class comment. */ public static final String PROPERTY_BEFORE_BEAN = "beforeBean"; /** * The name of the read-write bound property that holds the target bean. * * @see #getBean() * @see #setBean(Object) */ public static final String PROPERTY_BEAN = "bean"; /** * The property name used in the PropertyChangeEvent that is fired * after the bean property fires its PropertyChangeEvent. * Useful to perform an operation after listeners that handle the * bean change are notified. See also the class comment. */ public static final String PROPERTY_AFTER_BEAN = "afterBean"; /** * The name of the read-only bound bean property that * indicates whether one of the observed properties has changed. * * @see #isChanged() */ public static final String PROPERTY_CHANGED = "changed"; // Fields ***************************************************************** /** * Holds a ValueModel that holds the bean * that in turn holds the adapted property. * * @see #getBean() * @see #setBean(Object) */ private final ValueModel beanChannel; /** * Specifies whether we observe property changes and in turn * fire state changes. * * @see #getObserveChanges() */ private final boolean observeChanges; /** * Maps property names to the associated SimplePropertyAdapters. * * @see #getValueModel(String) * @see #getValueModel(String, String, String) */ private final Map propertyAdapters; /** * Refers to the IndirectPropertyChangeSupport that is used to redirect * PropertyChangelisteners to the current target bean. */ private IndirectPropertyChangeSupport indirectChangeSupport; /** * Refers to the old bean. Used as old value if the bean changes. * Updated after a bean change in the BeanChangeHandler. */ B storedOldBean; /** * Indicates whether a property in the current target been has changed. * Will be reset to {@code false} every time the target bean changes. * * @see #isChanged() * @see #setBean(Object) */ private boolean changed = false; /** * The {@code PropertyChangeListener} used to handle changes * in the bean properties. A new instance is created every time * the target bean changes. */ private PropertyChangeListener propertyChangeHandler; // Instance creation **************************************************** /** * Constructs a BeanAdapter for the given bean; * does not observe changes.

* * Installs a default bean channel that checks the identity not equity * to ensure that listeners are re-registered properly if the old and * new bean are equal but not the same. * * @param bean the bean that owns the properties to adapt */ public BeanAdapter(B bean) { this(bean, false); } /** * Constructs a BeanAdapter for the given bean; * observes changes if specified.

* * Installs a default bean channel that checks the identity not equity * to ensure that listeners are reregistered properly if the old and * new bean are equal but not the same. * * @param bean the bean that owns the properties to adapt * @param observeChanges {@code true} to observe changes of bound * or constrained properties, {@code false} to ignore changes * @throws PropertyUnboundException if {@code observeChanges} * is true but the property is unbound, i. e. the {@code bean} * does not provide a pair of methods to register a multicast * PropertyChangeListener */ public BeanAdapter( B bean, boolean observeChanges) { this(new ValueHolder(bean, true), observeChanges); } /** * Constructs a BeanAdapter for the given bean channel; * does not observe changes.

* * It is strongly recommended that the bean channel checks the identity * not equity. This ensures that listeners are reregistered properly if * the old and new bean are equal but not the same. * * @param beanChannel the ValueModel that holds the bean */ public BeanAdapter(ValueModel beanChannel) { this(beanChannel, false); } /** * Constructs a BeanAdapter for the given bean channel; * observes changes if specified.

* * It is strongly recommended that the bean channel checks the identity * not equity. This ensures that listeners are reregistered properly if * the old and new bean are equal but not the same. * * @param beanChannel the ValueModel that holds the bean * @param observeChanges {@code true} to observe changes of bound * or constrained properties, {@code false} to ignore changes * * @throws IllegalArgumentException if the beanChannel is a ValueHolder * that has the identityCheck feature disabled * @throws PropertyUnboundException if {@code observeChanges} * is true but the property is unbound, i. e. the {@code bean} * does not provide a pair of methods to register a multicast * PropertyChangeListener */ public BeanAdapter( ValueModel beanChannel, boolean observeChanges) { this.beanChannel = beanChannel != null ? beanChannel : new ValueHolder(null, true); checkBeanChannelIdentityCheck(beanChannel); this.observeChanges = observeChanges; this.propertyAdapters = new HashMap(); this.beanChannel.addValueChangeListener(new BeanChangeHandler()); B initialBean = getBean(); if (initialBean != null) { if (observeChanges && !BeanUtils.supportsBoundProperties(getBeanClass(initialBean))) { throw new PropertyUnboundException( "The bean must provide support for listening on property changes " + "as described in section 7.4.5 of the Java Bean Specification."); } addChangeHandlerTo(initialBean); } storedOldBean = initialBean; } // Accessors ************************************************************ /** * Returns the ValueModel that holds the bean that in turn holds * the adapted properties. This bean channel is shared by the * PropertyAdapters created by the factory method * {@code #getValueModel}. * * @return the ValueModel that holds the bean that in turn * holds the adapted properties * * @see #getBean() * @see #setBean(Object) * * @since 1.3 */ public ValueModel getBeanChannel() { return beanChannel; } /** * Returns the Java Bean that holds the adapted properties. * * @return the Bean that holds the adapted properties * * @see #setBean(Object) */ public B getBean() { return (B) beanChannel.getValue(); } /** * Sets a new Java Bean as holder of the adapted properties. * Notifies any registered value listeners that are registered * with the adapting ValueModels created in {@code #getValueModel}. * Also notifies listeners that have been registered with this adapter * to observe the bound property bean.

* * Resets the changed state to {@code false}.

* * If this adapter observes bean changes, the bean change handler * will be removed from the former bean and will be added to the new bean. * Hence, if the new bean is {@code null}, this adapter has no * listener registered with a bean. * And so, {@code setBean(null)} can be used as a clean release method * that allows to use this adapter later again. * * @param newBean the new holder of the adapted properties * * @see #getBean() * @see #isChanged() * @see #resetChanged() * @see #release() */ public void setBean(B newBean) { beanChannel.setValue(newBean); resetChanged(); } /** * Answers whether this adapter observes changes in the * adapted Bean properties. * * @return true if this adapter observes changes, false if not */ public boolean getObserveChanges() { return observeChanges; } /* * Sets whether changes in the bean's bound property shall be observed. * As a requirement the bean must provide support for listenening * on property changes. * * @param newValue true to observe changes, false to ignore them public void setObserveChanges(boolean newValue) { if (newValue == getObserveChanges()) return; observeChanges = newValue; Object bean = getBean(); removePropertyChangeHandler(bean); addPropertyChangeHandler(bean); } */ // Accessing Property Values ********************************************** /** * Returns the value of specified bean property, {@code null} * if the current bean is {@code null}.

* * This operation is supported only for readable bean properties. * * @param propertyName the name of the property to be read * @return the value of the adapted bean property, null if the bean is null * * @throws NullPointerException if propertyName is null * @throws UnsupportedOperationException if the property is write-only * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the value could not be read */ public Object getValue(String propertyName) { return getValueModel(propertyName).getValue(); } /** * Sets the given new value for the specified bean property. Does nothing * if this adapter's bean is {@code null}. If the setter associated * with the propertyName throws a PropertyVetoException, it is silently * ignored.

* * Notifies the associated value change listeners if the bean reports * a property change. Note that a bean may suppress PropertyChangeEvents * if the old and new value are the same, or if the old and new value * are equal.

* * This operation is supported only for writable bean properties. * * @param propertyName the name of the property to set * @param newValue the value to set * * @throws NullPointerException if propertyName is null * @throws UnsupportedOperationException if the property is read-only * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the new value could not be set */ public void setValue(String propertyName, Object newValue) { getValueModel(propertyName).setValue(newValue); } /** * Sets a new value for the specified bean property. Does nothing if the * bean is {@code null}. If the setter associated with the propertyName * throws a PropertyVetoException, this methods throws the same exception.

* * Notifies the associated value change listeners if the bean reports * a property change. Note that a bean may suppress PropertyChangeEvents * if the old and new value are the same, or if the old and new value * are equal.

* * This operation is supported only for writable bean properties. * * @param propertyName the name of the property to set * @param newValue the value to set * * @throws NullPointerException if propertyName is null * @throws UnsupportedOperationException if the property is read-only * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the new value could not be set * @throws PropertyVetoException if the bean setter * throws a PropertyVetoException * * @since 1.1 */ public void setVetoableValue(String propertyName, Object newValue) throws PropertyVetoException { getValueModel(propertyName).setVetoableValue(newValue); } // Creating and Accessing Adapting ValueModels **************************** /** * Looks up and lazily creates a ValueModel that adapts * the bound property with the specified name. Uses the * Bean introspection to look up the getter and setter names.

* * Subsequent calls to this method with the same property name * return the same ValueModel.

* * To prevent potential runtime errors this method eagerly looks up * the associated PropertyDescriptor if the target bean is not null.

* * For each property name all calls to this method and to * {@code #getValueModel(String, String, String)} must use * the same getter and setter names. Attempts to violate this constraint * will be rejected with an IllegalArgumentException. Especially once * you've called this method you must not call * {@code #getValueModel(String, String, String)} with a non-null * getter or setter name. And vice versa, once you've called the latter * method with a non-null getter or setter name, you must not call * this method.

* * This method uses a return type of AbstractValueModel, not a ValueModel. * This makes {@link #setVetoableValue(String, Object)} visible. It also * makes the AbstractValueModel convenience type converters available, * which can significantly shrink the source code necessary to read and * write values from/to these models. * * @param propertyName the name of the property to adapt * @return a ValueModel that adapts the property with the specified name * * @throws NullPointerException if propertyName is null * @throws PropertyNotFoundException if the property could not be found * @throws IllegalArgumentException * if {@code #getValueModel(String, String, String)} has been * called before with the same property name and a non-null getter * or setter name */ public SimplePropertyAdapter getValueModel(String propertyName) { return getValueModel(propertyName, null, null); } /** * Looks up and lazily creates a ValueModel that adapts the bound property * with the specified name. Unlike {@code #getValueModel(String)} * this method bypasses the Bean Introspection and uses the given getter * and setter names to setup the access to the adapted Bean property.

* * Subsequent calls to this method with the same parameters * will return the same ValueModel.

* * To prevent potential runtime errors this method eagerly looks up * the associated PropertyDescriptor if the target bean is not null.

* * For each property name all calls to this method * and to {@code #getValueModel(String)} must use the same * getter and setter names. Attempts to violate this constraint * will be rejected with an IllegalArgumentException. Especially * once you've called this method with a non-null getter or setter name, * you must not call {@code #getValueModel(String)}. And vice versa, * once you've called the latter method you must not call this method * with a non-null getter or setter name.

* * This method uses a return type of AbstractValueModel, not a ValueModel. * This makes {@link #setVetoableValue(String, Object)} visible. It also * makes the AbstractValueModel convenience type converters available, * which can significantly shrink the source code necessary to read and * write values from/to these models. * * @param propertyName the name of the property to adapt * @param getterName the name of the method that reads the value * @param setterName the name of the method that sets the value * @return a ValueModel that adapts the property with the specified name * * @throws NullPointerException if propertyName is null * @throws PropertyNotFoundException if the property could not be found * @throws IllegalArgumentException if this method has been called before * with the same property name and different getter or setter names */ public SimplePropertyAdapter getValueModel(String propertyName, String getterName, String setterName) { checkNotBlank(propertyName, MUST_NOT_BE_BLANK, "property name"); SimplePropertyAdapter adaptingModel = getPropertyAdapter(propertyName); if (adaptingModel == null) { adaptingModel = createPropertyAdapter(propertyName, getterName, setterName); propertyAdapters.put(propertyName, adaptingModel); } else { checkArgument(Objects.equals(getterName, adaptingModel.getterName) && Objects.equals(setterName, adaptingModel.setterName), "You must not invoke this method twice " + "with different getter and/or setter names."); } return adaptingModel; } /** * Looks up and returns the SimplePropertyAdapter that adapts * the bound property with the specified name. * * @param propertyName the name of the adapted property * @return a SimplePropertyAdapter that adapts the bound property * with the specified name or null, if none has been created before */ SimplePropertyAdapter getPropertyAdapter(String propertyName) { return propertyAdapters.get(propertyName); } /** * Creates and returns a SimplePropertyAdapter that adapts * the bound property with the specified name. * * @param propertyName the name of the property to adapt * @param getterName the name of the method that reads the value * @param setterName the name of the method that sets the value * @return a SimplePropertyAdapter that adapts the property * with the specified name * * @since 1.4 */ protected SimplePropertyAdapter createPropertyAdapter( String propertyName, String getterName, String setterName) { return new SimplePropertyAdapter(propertyName, getterName, setterName); } // Accessing the Changed State ******************************************** /** * Answers whether a bean property has changed since the changed state * has been reset. The changed state is implicitly reset every time * the target bean changes. * * @return true if a property of the current target bean * has changed since the last reset */ public boolean isChanged() { return changed; } /** * Resets this tracker's changed state to {@code false}. */ public void resetChanged() { setChanged(false); } /** * Sets the changed state to the given value. Invoked by the global * PropertyChangeHandler that observes all bean changes. Also invoked * by {@code #resetChanged}. * * @param newValue the new changed state */ private void setChanged(boolean newValue) { boolean oldValue = isChanged(); changed = newValue; firePropertyChange(PROPERTY_CHANGED, oldValue, newValue); } // Managing Bean Property Change Listeners ******************************* /** * Adds a PropertyChangeListener to the list of bean listeners. The * listener is registered for all bound properties of the target bean.

* * The listener will be notified if and only if this BeanAdapter's current * bean changes a property. It'll not be notified if the bean changes.

* * If listener is {@code null}, no exception is thrown and no action * is performed. * * @param listener the PropertyChangeListener to be added * * @see #removeBeanPropertyChangeListener(PropertyChangeListener) * @see #removeBeanPropertyChangeListener(String, PropertyChangeListener) * @see #addBeanPropertyChangeListener(String, PropertyChangeListener) * @see #getBeanPropertyChangeListeners() */ public synchronized void addBeanPropertyChangeListener( PropertyChangeListener listener) { if (listener == null) { return; } if (indirectChangeSupport == null) { indirectChangeSupport = new IndirectPropertyChangeSupport(beanChannel); } indirectChangeSupport.addPropertyChangeListener(listener); } /** * Removes a PropertyChangeListener from the list of bean listeners. * This method should be used to remove PropertyChangeListeners that * were registered for all bound properties of the target bean.

* * If listener is {@code null}, no exception is thrown and no action is performed. * * @param listener the PropertyChangeListener to be removed * * @see #addBeanPropertyChangeListener(PropertyChangeListener) * @see #addBeanPropertyChangeListener(String, PropertyChangeListener) * @see #removeBeanPropertyChangeListener(String, PropertyChangeListener) * @see #getBeanPropertyChangeListeners() */ public synchronized void removeBeanPropertyChangeListener( PropertyChangeListener listener) { if (listener == null || indirectChangeSupport == null) { return; } indirectChangeSupport.removePropertyChangeListener(listener); } /** * Adds a PropertyChangeListener to the list of bean listeners for a * specific property. The specified property may be user-defined.

* * The listener will be notified if and only if this BeanAdapter's * current bean changes the specified property. It'll not be notified * if the bean changes. If you want to observe property changes and * bean changes, you may observe the ValueModel that adapts this property * - as returned by {@code #getValueModel(String)}.

* * Note that if the bean is inheriting a bound property, then no event * will be fired in response to a change in the inherited property.

* * If listener is {@code null}, no exception is thrown and no action is performed. * * @param propertyName one of the property names listed above * @param listener the PropertyChangeListener to be added * * @see #removeBeanPropertyChangeListener(String, PropertyChangeListener) * @see #addBeanPropertyChangeListener(String, PropertyChangeListener) * @see #getBeanPropertyChangeListeners(String) */ public synchronized void addBeanPropertyChangeListener( String propertyName, PropertyChangeListener listener) { if (listener == null) { return; } if (indirectChangeSupport == null) { indirectChangeSupport = new IndirectPropertyChangeSupport(beanChannel); } indirectChangeSupport.addPropertyChangeListener(propertyName, listener); } /** * Removes a PropertyChangeListener from the listener list for a specific * property. This method should be used to remove PropertyChangeListeners * that were registered for a specific bound property.

* * If listener is {@code null}, no exception is thrown and no action is performed. * * @param propertyName a valid property name * @param listener the PropertyChangeListener to be removed * * @see #addBeanPropertyChangeListener(String, PropertyChangeListener) * @see #removeBeanPropertyChangeListener(PropertyChangeListener) * @see #getBeanPropertyChangeListeners(String) */ public synchronized void removeBeanPropertyChangeListener( String propertyName, PropertyChangeListener listener) { if (listener == null || indirectChangeSupport == null) { return; } indirectChangeSupport.removePropertyChangeListener(propertyName, listener); } // Requesting Listener Sets *********************************************** /** * Returns an array of all the property change listeners * registered on this component. * * @return all of this component's {@code PropertyChangeListener}s * or an empty array if no property change * listeners are currently registered * * @see #addBeanPropertyChangeListener(PropertyChangeListener) * @see #removeBeanPropertyChangeListener(PropertyChangeListener) * @see #getBeanPropertyChangeListeners(String) * @see java.beans.PropertyChangeSupport#getPropertyChangeListeners() */ public synchronized PropertyChangeListener[] getBeanPropertyChangeListeners() { if (indirectChangeSupport == null) { return new PropertyChangeListener[0]; } return indirectChangeSupport.getPropertyChangeListeners(); } /** * Returns an array of all the listeners which have been associated * with the named property. * * @param propertyName the name of the property to lookup listeners * @return all of the {@code PropertyChangeListeners} associated with * the named property or an empty array if no listeners have * been added * * @see #addBeanPropertyChangeListener(String, PropertyChangeListener) * @see #removeBeanPropertyChangeListener(String, PropertyChangeListener) * @see #getBeanPropertyChangeListeners() */ public synchronized PropertyChangeListener[] getBeanPropertyChangeListeners(String propertyName) { if (indirectChangeSupport == null) { return new PropertyChangeListener[0]; } return indirectChangeSupport.getPropertyChangeListeners(propertyName); } // Releasing PropertyChangeListeners ************************************** /** * Removes the PropertyChangeHandler from the observed bean, if the bean * is not {@code null} and if bean property changes are observed. * Also removes all listeners from the bean that have been registered * with {@code #addBeanPropertyChangeListener} before.

* * BeanAdapters that observe changes have a PropertyChangeListener * registered with the target bean. Hence, a bean has a reference * to all BeanAdapters that observe it. To avoid memory leaks * it is recommended to remove this listener if the bean lives much longer * than the BeanAdapter, enabling the garbage collector to remove the adapter. * To do so, you can call {@code setBean(null)} or set the * bean channel's value to null. * As an alternative you can use event listener lists in your beans * that implement references with {@code WeakReference}.

* * Setting the bean to null has side-effects, for example the adapter * fires a change event for the bound property bean and other properties. * And the value of ValueModel's vended by this adapter may change. * However, typically this is fine and setting the bean to null * is the first choice for removing the reference from the bean to the adapter. * Another way to clear the reference from the target bean is * to call {@code #release}; it has no side-effects.

* * Since version 2.0.4 it is safe to call this method multiple times, * however, the adapter must not be used anymore once #release * has been called. * * @see #setBean(Object) * @see java.lang.ref.WeakReference */ public synchronized void release() { removeChangeHandlerFrom(getBean()); if (indirectChangeSupport != null) { indirectChangeSupport.removeAll(); } } // Changing the Bean & Adding and Removing the PropertyChangeHandler ****** private void setBean0(B oldBean, B newBean) { firePropertyChange(PROPERTY_BEFORE_BEAN, oldBean, newBean, true); removeChangeHandlerFrom(oldBean); forwardAllAdaptedValuesChanged(oldBean, newBean); resetChanged(); addChangeHandlerTo(newBean); firePropertyChange(PROPERTY_BEAN, oldBean, newBean, true); firePropertyChange(PROPERTY_AFTER_BEAN, oldBean, newBean, true); } /** * Iterates over all internal property adapters to notify them * about a bean change from oldBean to newBean. These adapters then notify * their observers to inform them about a value change - if any.

* * Iterates over a copy of the property adapters to avoid * ConcurrentModifications that may be thrown if a listener creates * a new SimplePropertyAdapter by requesting an adapting model using * {@code #getValueModel}. * * @param oldBean the bean before the change * @param newBean the bean after the change */ private void forwardAllAdaptedValuesChanged(B oldBean, B newBean) { Object[] adapters = propertyAdapters.values().toArray(); for (Object adapter : adapters) { ((SimplePropertyAdapter) adapter).setBean0(oldBean, newBean); } } /** * Iterates over all internal property adapters to notify them * about a value change in the bean. These adapters then notify * their observers to inform them about a value change - if any.

* * Iterates over a copy of the property adapters to avoid * ConcurrentModifications that may be thrown if a listener creates * a new SimplePropertyAdapter by requesting an adapting model using * {@code #getValueModel}. */ private void forwardAllAdaptedValuesChanged() { B currentBean = getBean(); Object[] adapters = propertyAdapters.values().toArray(); for (Object adapter : adapters) { ((SimplePropertyAdapter) adapter).fireChange(currentBean); } } /** * Adds a property change listener to the given bean if we observe changes * and the bean is not null. First checks whether the bean class * supports bound properties, i.e. it provides a pair of methods * to register multicast property change event listeners; * see section 7.4.1 of the Java Beans specification for details. * * @param bean the bean to add a property change handler. * @throws PropertyUnboundException * if the bean does not support bound properties * @throws PropertyNotBindableException * if the property change handler cannot be added successfully * * @see #removeChangeHandlerFrom(Object) */ private void addChangeHandlerTo(B bean) { if (!observeChanges || bean == null) { return; } propertyChangeHandler = new PropertyChangeHandler(); // TODO: Replace the first with the second line if getBeanClass(bean) // may return a class other than bean.getClass(). BeanUtils.addPropertyChangeListener(bean, (Class)null, propertyChangeHandler); // BeanUtils.addPropertyChangeListener(bean, getBeanClass(bean), propertyChangeHandler); } /** * Removes the formerly added property change handler from the given bean * if we observe changes and the bean is not null and we haven't called * this method before. * * @param bean the bean to remove the property change handler from. * @throws PropertyUnboundException * if the bean does not support bound properties * @throws PropertyNotBindableException * if the property change handler cannot be removed successfully * * @see #addChangeHandlerTo(Object) */ private void removeChangeHandlerFrom(B bean) { if (!observeChanges || bean == null || propertyChangeHandler == null) { return; } // TODO: Replace the first with the second line if getBeanClass(bean) // may return a class other than bean.getClass(). BeanUtils.removePropertyChangeListener(bean, (Class)null, propertyChangeHandler); // BeanUtils.removePropertyChangeListener(bean, getBeanClass(bean), propertyChangeHandler); propertyChangeHandler = null; } // Helper Methods to Get and Set a Property Value ************************* /** * Returns the Java Bean class used by this adapter. * The current implementation just returns the given bean's class.

* * A future version may return a type other than the concrete * class of the given bean. This beanClass could be specified * in a new set of constructors. This is useful if the beans * are specified by public interfaces, and implemented by * package private classes. In this case, the class of the given bean * object shall be checked against the specified type. * * @param bean the bean that may be used to lookup the class from * @return the Java Bean class used for this adapter. */ private Class getBeanClass(B bean) { return bean.getClass(); // TODO: A future version shall add a check like // beanClass.isInstance(bean) if the beanClass // has been specified in the constructor. } /** * Returns the value of the specified property of the given bean, * {@code null} if the bean is {@code null}. * * @param bean the bean to read the value from * @param propertyDescriptor describes the property to be read * @return the bean's property value */ private Object getValue0(B bean, PropertyAccessor propertyDescriptor) { return bean == null ? null : propertyDescriptor.getValue(bean); } /** * Sets the given object as new value of the specified property of the * given bean. Does nothing if the bean is null. This write operation is * supported only for writable bean properties. * * @param bean the bean that holds the adapted property * @param propertyDescriptor describes the property to be set * @param newValue the property value to be set * * @throws NullPointerException if the bean is null * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the write access failed * @throws PropertyVetoException if the invoked bean setter * throws a PropertyVetoException */ private void setValue0(B bean, PropertyAccessor propertyDescriptor, Object newValue) throws PropertyVetoException { propertyDescriptor.setValue(bean, newValue); } /** * Throws an IllegalArgumentException if the given ValueModel * is a ValueHolder that has the identityCheck feature disabled. */ private static void checkBeanChannelIdentityCheck(ValueModel valueModel) { if (!(valueModel instanceof ValueHolder)) { return; } ValueHolder valueHolder = (ValueHolder) valueModel; if (!valueHolder.isIdentityCheckEnabled()) { throw new IllegalArgumentException( "The bean channel must have the identity check enabled."); } } // Helper Classes ********************************************************* /** * Listens to changes of the bean. */ private final class BeanChangeHandler implements PropertyChangeListener { /** * The bean has been changed. Uses the stored old bean instead of * the event's old value, because the latter can be null. * If the event's new value is null, the new bean is requested * from the bean channel. * * @param evt the property change event to be handled */ @Override public void propertyChange(PropertyChangeEvent evt) { B newBean = evt.getNewValue() != null ? (B) evt.getNewValue() : getBean(); setBean0(storedOldBean, newBean); storedOldBean = newBean; } } /** * Listens to changes of all bean properties. Fires property changes * if the associated property or an arbitrary set of properties has changed. */ private final class PropertyChangeHandler implements PropertyChangeListener { /** * A bean property has been changed. Sets the changed state to true. * Checks whether the observed or multiple properties have changed. * If so, notifies all registered listeners about the change. * * @param evt the property change event to be handled */ @Override public void propertyChange(PropertyChangeEvent evt) { setChanged(true); String propertyName = evt.getPropertyName(); if (propertyName == null) { forwardAllAdaptedValuesChanged(); } else { SimplePropertyAdapter adapter = getPropertyAdapter(propertyName); if (adapter != null) { adapter.fireChange(evt.getOldValue(), evt.getNewValue()); } } } } /** * Implements the access to the individual bean properties. * All SimplePropertyAdapters created by this BeanAdapter * share a single PropertyChangeListener that is used to * fire value changes in this SimplePropertyAdapter.

* * This class is public to enable reflection access. */ public class SimplePropertyAdapter extends AbstractValueModel { /** * Holds the name of the adapted property. */ private final String propertyName; /** * Holds the optional name of the property's getter. * Used to create the PropertyDescriptor. * Also used to reject potential misuse of * {@link BeanAdapter#getValueModel(String)} and * {@link BeanAdapter#getValueModel(String, String, String)}. * See the latter methods for details. */ final String getterName; /** * Holds the optional name of the property's setter. * Used to create the PropertyDescriptor. * Also used to reject potential misuse of * {@link BeanAdapter#getValueModel(String)} and * {@link BeanAdapter#getValueModel(String, String, String)}. * See the latter methods for details. */ final String setterName; /** * Describes the property accessor; basically a getter and setter. */ private transient PropertyAccessor cachedPropertyDescriptor; /** * Holds the bean class associated with the cached property descriptor. */ private Class cachedBeanClass; // Instance Creation -------------------------------------------------- /** * Constructs a SimplePropertyAdapter for the given property name, * getter and setter name. * * @param propertyName the name of the property to adapt * @param getterName the name of the method that reads the value * @param setterName the name of the method that sets the value */ protected SimplePropertyAdapter(String propertyName, String getterName, String setterName) { this.propertyName = propertyName; this.getterName = getterName; this.setterName = setterName; // Eagerly check the existence of the property to adapt. B bean = getBean(); if (bean != null) { getPropertyAccessor(bean); } } // Implementing ValueModel -------------------------------------------- /** * Returns the value of the adapted bean property, or null * if the bean is null. * * @return the value of the adapted bean property, * null if the bean is null */ @Override public Object getValue() { B bean = getBean(); if (bean == null) { return null; } return getValue0(bean, getPropertyAccessor(bean)); } /** * Sets the given object as new value of the adapted bean property. * Does nothing if the bean is {@code null}. If the bean setter * throws a PropertyVetoException, it is silently ignored. * This write operation is supported only for writable bean properties.

* * Notifies any registered value listener if the bean reports * a property change. Note that a bean may suppress PropertyChangeEvents * if the old and new value are the same, or if the old and new value * are equal. * * @param newValue the value to set * * @throws UnsupportedOperationException if the property is read-only * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the new value could not be set */ @Override public void setValue(Object newValue) { B bean = getBean(); if (bean == null) { return; } try { setValue0(bean, getPropertyAccessor(bean), newValue); } catch (PropertyVetoException e) { // Silently ignore that someone vetoed against this change } } /** * Sets the given object as new value of the adapted bean property. * Does nothing if the bean is {@code null}. If the bean setter * throws a PropertyVetoExeption, this method throws the same exception. * This write operation is supported only for writable bean properties.

* * Notifies any registered value listener if the bean reports * a property change. Note that a bean may suppress PropertyChangeEvents * if the old and new value are the same, or if the old and new value * are equal. * * @param newValue the value to set * * @throws UnsupportedOperationException if the property is read-only * @throws PropertyNotFoundException if the property could not be found * @throws PropertyAccessException if the new value could not be set * @throws PropertyVetoException if the invoked bean setter * throws a PropertyVetoException * * @since 1.1 */ public void setVetoableValue(Object newValue) throws PropertyVetoException { B bean = getBean(); if (bean == null) { return; } setValue0(bean, getPropertyAccessor(bean), newValue); } // Accessing the Cached Property Descriptor -------------------------- /** * Looks up, lazily initializes and returns a PropertyAccessor * for the given Java Bean and name of the adapted property. * The concrete lookup is done by the current PropertyAccessorProvider, * which is by default a provider that uses the Java Bean introspection.

* * The cached accessor is considered invalid, if the bean's class * has changed. In this case we recompute the accessor. * * @param bean the bean that holds the property * @return the PropertyAccessor as returned by the provider * @throws PropertyNotFoundException if the property could not be found */ private PropertyAccessor getPropertyAccessor(B bean) { Class beanClass = getBeanClass(bean); if (cachedPropertyDescriptor == null || beanClass != cachedBeanClass) { cachedPropertyDescriptor = PropertyAccessors.getProvider().getAccessor( beanClass, propertyName, getterName, setterName); cachedBeanClass = beanClass; } return cachedPropertyDescriptor; } protected void fireChange(B currentBean) { Object newValue; if (currentBean == null) { newValue = null; } else { PropertyAccessor propertyDescriptor = getPropertyAccessor(currentBean); boolean isWriteOnly = propertyDescriptor.isWriteOnly(); newValue = isWriteOnly ? null : getValue0(currentBean, propertyDescriptor); } fireValueChange(null, newValue); } protected void fireChange(Object oldValue, Object newValue) { fireValueChange(oldValue, newValue, true); } protected void setBean0(B oldBean, B newBean) { Object oldValue; Object newValue; if (oldBean == null) { oldValue = null; } else { PropertyAccessor propertyAccessor = getPropertyAccessor(oldBean); boolean isWriteOnly = propertyAccessor.isWriteOnly(); oldValue = isWriteOnly ? null : getValue0(oldBean, propertyAccessor); } if (newBean == null) { newValue = null; } else { PropertyAccessor propertyAccessor = getPropertyAccessor(newBean); boolean isWriteOnly = propertyAccessor.isWriteOnly(); newValue = isWriteOnly ? null : getValue0(newBean, propertyAccessor); } if (oldValue != null || newValue != null) { fireValueChange(oldValue, newValue, true); } } @Override protected String paramString() { B bean = getBean(); String beanType = null; Object value = getValue(); String valueType = null; String propertyDescriptorName = null; String propertyType = null; Method propertyGetter = null; Method propertySetter = null; if (bean != null) { beanType = bean.getClass().getName(); valueType = value == null ? null : value.getClass().getName(); PropertyAccessor propertyDescriptor = getPropertyAccessor(bean); propertyDescriptorName = propertyDescriptor.getPropertyName(); propertyType = propertyDescriptor.getPropertyType().getName(); propertyGetter = propertyDescriptor.getReadMethod(); propertySetter = propertyDescriptor.getWriteMethod(); } return "bean=" + bean + "; bean type=" + beanType + "; value=" + value + "; value type=" + valueType + "; property name=" + propertyDescriptorName + "; property type=" + propertyType + "; property getter=" + propertyGetter + "; property setter=" + propertySetter; } } }