001package jmri;
002
003import javax.annotation.Nonnull;
004
005/**
006 * Record an object and its expected state within a specific scenario. This can
007 * be used in collections, for example as a routing through a set of turnouts,
008 * where the turnouts and their state when all turnouts are routed for that
009 * routing can be iterated over in a single loop with reference to a single
010 * collection.
011 *
012 * @author Randall Wood Copyright 2017
013 * @param <T> the type of object this contains the expected state for
014 * @param <S> the type of expected state this contains
015 */
016public interface ExpectedState<T extends Object, S extends Object> {
017
018    /**
019     * Constant for the property name when {@link #setExpectedState(java.lang.Object)} fires
020     * a {@link java.beans.PropertyChangeEvent}.
021     */
022    String EXPECTED_STATE = "expectedState";
023
024    /**
025     * Get the expected state. This state should not change as the state of the
026     * NamedBean changes.
027     *
028     * @return the expected state
029     */
030    S getExpectedState();
031
032    /**
033     * Set the expected state.
034     * <p>
035     * If UnsupportedOperationException is not thrown, this must fire a
036     * {@link java.beans.PropertyChangeEvent} with the name
037     * {@value #EXPECTED_STATE}
038     *
039     * @param state the new expected state
040     * @throws UnsupportedOperationException if the implementing class does not
041     *                                       allow states to be set
042     */
043    void setExpectedState(S state) throws UnsupportedOperationException;
044
045    /**
046     * Get the Object this records the expected state for.
047     *
048     * @return the associated object
049     */
050    @Nonnull
051    T getObject();
052}