001package jmri.beans;
002
003import java.beans.VetoableChangeListener;
004import javax.annotation.Nonnull;
005import javax.annotation.CheckForNull;
006
007/**
008 * A set of methods that would need to be implemented to ensure the implementing
009 * class provides a complete external interface for vetoable property changes.
010 * This interface is merely a convenience for developers to ensure support for
011 * vetoable property change listening is thorough, if not complete. Developers
012 * of classes implementing this interface still need to ensure that
013 * {@link java.beans.VetoableChangeListener}s are queried and that
014 * {@link java.beans.PropertyChangeEvent}s are fired when properties are set.
015 *
016 * {@link jmri.beans.ConstrainedArbitraryBean} and
017 * {@link jmri.beans.ConstrainedBean} provide complete implementations of this
018 * interface.
019 *
020 * This interface defines all public methods of
021 * {@link java.beans.VetoableChangeSupport} except the methods to fire
022 * PropertyChangeEvents.
023 *
024 * @author Randall Wood
025 */
026public interface VetoableChangeProvider {
027
028    /**
029     * Add a {@link java.beans.VetoableChangeListener} to the listener list.
030     *
031     * @param listener The VetoableChangeListener to be added
032     */
033    void addVetoableChangeListener(@CheckForNull VetoableChangeListener listener);
034
035    /**
036     * Add a {@link java.beans.VetoableChangeListener} for a specific property.
037     *
038     * @param propertyName The name of the property to listen on.
039     * @param listener     The VetoableChangeListener to be added
040     */
041    public void addVetoableChangeListener(@CheckForNull String propertyName, @CheckForNull VetoableChangeListener listener);
042
043    /**
044     * Get all {@link java.beans.VetoableChangeListener}s currently attached to
045     * this object.
046     *
047     * @return An array of VetoableChangeListeners.
048     */
049    @Nonnull
050    VetoableChangeListener[] getVetoableChangeListeners();
051
052    /**
053     * Get all {@link java.beans.VetoableChangeListener}s currently listening to
054     * changes to the specified property.
055     *
056     * @param propertyName The name of the property of interest
057     * @return An array of VetoableChangeListeners.
058     */
059    @Nonnull
060    VetoableChangeListener[] getVetoableChangeListeners(@CheckForNull String propertyName);
061
062    /**
063     * Remove the specified listener from this object.
064     *
065     * @param listener The {@link java.beans.VetoableChangeListener} to remove.
066     */
067    void removeVetoableChangeListener(@CheckForNull VetoableChangeListener listener);
068
069    /**
070     * Remove the specified listener of the specified property from this object.
071     *
072     * @param propertyName The name of the property to stop listening to.
073     * @param listener     The {@link java.beans.VetoableChangeListener} to
074     *                     remove.
075     */
076    void removeVetoableChangeListener(@CheckForNull String propertyName, @CheckForNull VetoableChangeListener listener);
077
078}