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