com.jgoodies.binding.value.ValueHolder Maven / Gradle / Ivy
Show all versions of jgoodies-binding Show documentation
/*
* 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.value;
/**
* A simple {@link com.jgoodies.binding.value.ValueModel} implementation
* that holds a generic value.
* If the value changes, a {@code PropertyChangeEvent} is fired
* that can be observed using a {@code PropertyChangeListener}.
*
* Differences in the old and new value can be checked either using
* {@code ==} or {@code #equals}. The unbound property
* identityCheckEnabled determines which mechanism is used
* to check for changes in {@code #setValue(Object)}.
* This check can be overridden for individual changes by the boolean
* parameter in {@code #setValue(Object, boolean)}.
*
* Constraints: The value is of type {@code Object}.
*
* @author Karsten Lentzsch
* @version $Revision: 1.10 $
*
* @see ValueModel
* @see java.beans.PropertyChangeEvent
* @see java.beans.PropertyChangeListener
* @see com.jgoodies.binding.beans.ExtendedPropertyChangeSupport
*/
public final class ValueHolder extends AbstractValueModel {
/**
* Holds a value of type {@code Object} that is to be observed.
*/
private Object value;
/**
* Describes whether a value change event shall be fired if the
* old and new value are different. If {@code true} the old
* and new value are compared with {@code ==}. If {@code false}
* the values are compared with {@code #equals}.
*
* @see #setValue(Object, boolean)
* @see com.jgoodies.binding.beans.Model#firePropertyChange(String, Object, Object, boolean)
* @see com.jgoodies.binding.beans.ExtendedPropertyChangeSupport
*/
private boolean checkIdentity;
// Instance Creation ****************************************************
/**
* Constructs a {@code ValueHolder} with {@code null}
* as initial value.
*/
public ValueHolder() {
this(null);
}
/**
* Constructs a {@code ValueHolder} with the given initial value.
* By default the old and new value are compared using {@code #equals}
* when firing value change events.
*
* @param initialValue the initial value
*/
public ValueHolder(Object initialValue) {
this(initialValue, false);
}
/**
* Constructs a {@code ValueHolder} with the given initial value.
*
* @param initialValue the initial value
* @param checkIdentity true to compare the old and new value using
* {@code ==}, false to use {@code #equals}
*/
public ValueHolder(Object initialValue, boolean checkIdentity) {
value = initialValue;
this.checkIdentity = checkIdentity;
}
/**
* Constructs a {@code ValueHolder} with the specified initial
* boolean value that is converted to a {@code Boolean} object.
*
* @param initialValue the initial boolean value
*/
public ValueHolder(boolean initialValue) {
this(Boolean.valueOf(initialValue));
}
/**
* Constructs a {@code ValueHolder} with the specified initial
* double value that is converted to a {@code Double} object.
*
* @param initialValue the initial double value
*/
public ValueHolder(double initialValue) {
this(Double.valueOf(initialValue));
}
/**
* Constructs a {@code ValueHolder} with the specified initial
* float value that is converted to a {@code Float} object.
*
* @param initialValue the initial float value
*/
public ValueHolder(float initialValue) {
this(Float.valueOf(initialValue));
}
/**
* Constructs a {@code ValueHolder} with the specified initial
* int value that is converted to an {@code Integer} object.
*
* @param initialValue the initial int value
*/
public ValueHolder(int initialValue) {
this(Integer.valueOf(initialValue));
}
/**
* Constructs a {@code ValueHolder} with the specified initial
* long value that is converted to a {@code Long} object.
*
* @param initialValue the initial long value
*/
public ValueHolder(long initialValue) {
this(Long.valueOf(initialValue));
}
// ValueModel Implementation ********************************************
/**
* Returns the observed value.
*
* @return the observed value
*/
@Override
public Object getValue() {
return value;
}
/**
* Sets a new value. Fires a value change event if the old and new
* value differ. The difference is tested with {@code ==} if
* {@code isIdentityCheckEnabled} answers {@code true}.
* The values are compared with {@code #equals} if the
* identity check is disabled.
*
* @param newValue the new value
*/
@Override
public void setValue(Object newValue) {
setValue(newValue, isIdentityCheckEnabled());
}
// Optional Support for Firing Events on Identity Change ***************
/**
* Answers whether this ValueHolder fires value change events if
* and only if the old and new value are not the same.
*
* @return {@code true} if the old and new value are compared
* using {@code ==}, {@code false} if the values
* are compared using {@code #equals}
*/
public boolean isIdentityCheckEnabled() {
return checkIdentity;
}
/**
* Sets the comparison that is used to check differences between
* the old and new value when firing value change events.
* This is the default setting that is used when changing the value via
* {@code #setValue(Object)}. You can override this default setting
* by changing a value via {@code #setValue(Object, boolean)}.
*
* @param checkIdentity true to compare the old and new value using
* {@code ==}, false to use {@code #equals}
*/
public void setIdentityCheckEnabled(boolean checkIdentity) {
this.checkIdentity = checkIdentity;
}
/**
* Sets a new value. Fires a value change event if the old and new
* value differ. The difference is tested with {@code ==} if
* {@code checkIdentity} is {@code true}. The values are
* compared with {@code #equals} if the {@code checkIdentiy}
* parameter is set to {@code false}.
*
* Unlike general bean property setters, this method does not fire
* an event if the old and new value are {@code null}.
*
* @param newValue the new value
* @param checkIdentity true to compare the old and new value using
* {@code ==}, false to use {@code #equals}
*/
public void setValue(Object newValue, boolean checkIdentity) {
Object oldValue = getValue();
if (oldValue == newValue) {
return;
}
value = newValue;
fireValueChange(oldValue, newValue, checkIdentity);
}
}