Vetoable.java
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 }