001 /*
002 * Copyright 2012-2013 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of 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,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package griffon.core;
018
019 import java.beans.VetoableChangeListener;
020
021 /**
022 * Describes objects that provide bound and vetoable properties as specified in the
023 * <a href="http://docs.oracle.com/javase/tutorial/javabeans/TOC.html">Java
024 * Bean Specification</a>.
025 *
026 * @author Andres Almiray
027 * @since 1.2.0
028 */
029 public interface Vetoable extends Observable {
030 /**
031 * Add a VetoableListener to the listener list.
032 * The listener is registered for all properties.
033 * The same listener object may be added more than once, and will be called
034 * as many times as it is added.
035 * If <code>listener</code> is null, no exception is thrown and no action
036 * is taken.
037 *
038 * @param listener The VetoableChangeListener to be added
039 */
040
041 void addVetoableChangeListener(VetoableChangeListener listener);
042
043 /**
044 * Add a VetoableChangeListener for a specific property. The listener
045 * will be invoked only when a call on fireVetoableChange names that
046 * specific property.
047 * The same listener object may be added more than once. For each
048 * property, the listener will be invoked the number of times it was added
049 * for that property.
050 * If <code>propertyName</code> or <code>listener</code> is null, no
051 * exception is thrown and no action is taken.
052 *
053 * @param propertyName The name of the property to listen on.
054 * @param listener The VetoableChangeListener to be added
055 */
056
057 void addVetoableChangeListener(String propertyName, VetoableChangeListener listener);
058
059 /**
060 * Remove a VetoableChangeListener from the listener list.
061 * This removes a VetoableChangeListener that was registered
062 * for all properties.
063 * If <code>listener</code> was added more than once to the same event
064 * source, it will be notified one less time after being removed.
065 * If <code>listener</code> is null, or was never added, no exception is
066 * thrown and no action is taken.
067 *
068 * @param listener The VetoableChangeListener to be removed
069 */
070 void removeVetoableChangeListener(VetoableChangeListener listener);
071
072 /**
073 * Remove a VetoableChangeListener for a specific property.
074 * If <code>listener</code> was added more than once to the same event
075 * source for the specified property, it will be notified one less time
076 * after being removed.
077 * If <code>propertyName</code> is null, no exception is thrown and no
078 * action is taken.
079 * If <code>listener</code> is null, or was never added for the specified
080 * property, no exception is thrown and no action is taken.
081 *
082 * @param propertyName The name of the property that was listened on.
083 * @param listener The VetoableChangeListener to be removed
084 */
085
086 void removeVetoableChangeListener(String propertyName, VetoableChangeListener listener);
087
088 /**
089 * Returns the list of VetoableChangeListeners. If named vetoable change listeners
090 * were added, then VetoableChangeListenerProxy wrappers will returned
091 * <p/>
092 *
093 * @return List of VetoableChangeListeners and VetoableChangeListenerProxys
094 * if named property change listeners were added.
095 */
096 VetoableChangeListener[] getVetoableChangeListeners();
097
098 /**
099 * Returns an array of all the listeners which have been associated
100 * with the named property.
101 *
102 * @param propertyName The name of the property being listened to
103 * @return all the <code>VetoableChangeListeners</code> associated with
104 * the named property. If no such listeners have been added,
105 * or if <code>propertyName</code> is null, an empty array is
106 * returned.
107 */
108 VetoableChangeListener[] getVetoableChangeListeners(String propertyName);
109 }
|