001 /*
002 * Copyright 2002-2005 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016 package org.springframework.binding.value;
017
018 import java.beans.PropertyChangeListener;
019
020 /**
021 * Describes models with a generic access to a single value that allow
022 * to observe value changes. The value can be accessed using the
023 * <code>#getValue()</code>/<code>#setValue(Object)</code>/
024 * <code>#setValueSilently(Object, PropertyChangeListener)</code>
025 * methods. Observers can register instances of <code>PropertyChangeListener</code>
026 * to be notified if the value changes.
027 *
028 * <p>The listeners registered with this ValueModel using #addValueChangeListener
029 * will be invoked only with PropertyChangeEvents that have the name set to
030 * "value".
031 *
032 * <p>AbstractValueModel minimizes the effort required to implement this interface.
033 * It uses the PropertyChangeSupport to fire PropertyChangeEvents, and it adds
034 * PropertyChangeListeners for the specific property name "value". This ensures
035 * that the constraint mentioned above is met.
036 *
037 * @see org.springframework.binding.value.support.AbstractValueModel
038 *
039 * @author Karsten Lentzsch
040 * @author Keith Donald
041 * @author Oliver Hutchison
042 */
043 public interface ValueModel {
044
045 /**
046 * The name of the bound property <em>value</em>.
047 */
048 String VALUE_PROPERTY = "value";
049
050 /**
051 * Returns this model's value. In case of a write-only value,
052 * implementers may choose to either reject this operation or
053 * or return <code>null</code> or any other appropriate value.
054 *
055 * @return this model's value
056 */
057 Object getValue();
058
059 /**
060 * Sets a new value and if the value has changed notifies any registered
061 * value change listeners.
062 *
063 * @param newValue the value to be set
064 */
065 void setValue(Object newValue);
066
067 /**
068 * Sets a new value and if the value has changed notifies all registered
069 * value change listeners except for the specified listener to skip.
070 *
071 * @param newValue the value to be set
072 * @param listenerToSkip the <code>PropertyChangeListener</code> that should
073 * not be notified of this change (may be <code>null</code>).
074 */
075 void setValueSilently(Object newValue, PropertyChangeListener listenerToSkip);
076
077 /**
078 * Registers the given <code>PropertyChangeListener</code> with this
079 * ValueModel. The listener will be notified if the value has changed.
080 * The PropertyChangeEvents delivered to the listener must have the name
081 * set to "value". The latter ensures that all ValueModel implementers
082 * behave like the AbstractValueModel subclasses.<p>
083 *
084 * To comply with the above specification implementers can use
085 * the PropertyChangeSupport's #addPropertyChangeListener method
086 * that accepts a property name, so that listeners will be invoked only
087 * if that specific property has changed.
088 *
089 * @param listener the listener to be added
090 *
091 * @see org.springframework.binding.value.support.AbstractValueModel#addValueChangeListener(PropertyChangeListener)
092 */
093 void addValueChangeListener(PropertyChangeListener listener);
094
095 /**
096 * Deregisters the given <code>PropertyChangeListener</code> from this
097 * ValueModel.
098 *
099 * @param listener the listener to be removed
100 */
101 void removeValueChangeListener(PropertyChangeListener listener);
102
103 }