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