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