001package jmri.beans;
002
003import java.beans.PropertyChangeEvent;
004
005import javax.annotation.Nonnull;
006
007/**
008 * Sometimes an external object needs to be able to mute property changes to
009 * prevent bottlenecks in constrained systems (e.g. when reading a file that may
010 * add a large number of Turnouts or Sensors to JMRI's internal representation
011 * of the model railroad).
012 *
013 * @author Randall Wood Copyright 2020
014 */
015public interface SilenceablePropertyChangeProvider extends PropertyChangeProvider {
016
017    /**
018     * Suppress sending {@link PropertyChangeEvent}s for the named property.
019     * <p>
020     * Stopping the suppression of sending change events may send a
021     * PropertyChangeEvent if the property changed while silenced, but otherwise
022     * should not fire a PropertyChangeEvent.
023     *
024     * @param propertyName the name of the property to mute
025     * @param silenced     true if events are to be suppressed; false otherwise
026     * @throws IllegalArgumentException if propertyName represents a property
027     *                                  that should not be silenced
028     */
029    void setPropertyChangesSilenced(@Nonnull String propertyName, boolean silenced);
030}