001package jmri.beans;
002
003import java.beans.PropertyChangeListener;
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 property changes. This
010 * interface is merely a convenience for developers to ensure support for
011 * property change listening is thorough, if not complete. Developers of classes
012 * implementing this interface still need to ensure that
013 * {@link java.beans.PropertyChangeEvent}s are fired when properties are set.
014 * <p>
015 * {@link ArbitraryBean}, {@link Bean}, {@link ConstrainedBean},
016 * {@link PropertyChangeSupport}, and {@link VetoableChangeSupport} all provide
017 * complete implementations of this interface.
018 * <p>
019 * This interface defines all public methods of
020 * {@link java.beans.PropertyChangeSupport} except the methods to fire
021 * PropertyChangeEvents so that a consumer of an implementing class can be sure
022 * that it can listen for a property change.
023 *
024 * @author Randall Wood
025 */
026public interface PropertyChangeProvider {
027
028    /**
029     * Add a {@link java.beans.PropertyChangeListener} to the listener list.
030     *
031     * @param listener The PropertyChangeListener to be added
032     */
033    void addPropertyChangeListener(@CheckForNull PropertyChangeListener listener);
034
035    /**
036     * Add a {@link java.beans.PropertyChangeListener} for a specific property.
037     *
038     * @param propertyName The name of the property to listen on.
039     * @param listener     The PropertyChangeListener to be added
040     */
041    void addPropertyChangeListener(@CheckForNull String propertyName,
042            @CheckForNull PropertyChangeListener listener);
043
044    /**
045     * Get all {@link java.beans.PropertyChangeListener}s currently attached to
046     * this object.
047     *
048     * @return An array of PropertyChangeListeners.
049     */
050    @Nonnull
051    PropertyChangeListener[] getPropertyChangeListeners();
052
053    /**
054     * Get all {@link java.beans.PropertyChangeListener}s currently listening to
055     * changes to the specified property.
056     *
057     * @param propertyName the name of the property of interest
058     * @return an array of PropertyChangeListeners
059     */
060    @Nonnull
061    PropertyChangeListener[] getPropertyChangeListeners(@CheckForNull String propertyName);
062
063    /**
064     * Remove the specified listener from this object.
065     *
066     * @param listener The {@link java.beans.PropertyChangeListener} to remove.
067     */
068    void removePropertyChangeListener(@CheckForNull PropertyChangeListener listener);
069
070    /**
071     * Remove the specified listener of the specified property from this object.
072     *
073     * @param propertyName The name of the property to stop listening to.
074     * @param listener     The {@link java.beans.PropertyChangeListener} to
075     *                     remove.
076     */
077    void removePropertyChangeListener(@CheckForNull String propertyName,
078            @CheckForNull PropertyChangeListener listener);
079
080}