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}