001package jmri;
002
003import javax.annotation.Nonnull;
004
005/**
006 * Represent an string I/O on the layout.
007 * <p>
008 * A StringIO could for example be a display connected to an Arduino
009 * microcomputer that shows train departures of a station.
010 *
011 * @author Daniel Bergqvist Copyright (c) 2018
012 */
013public interface StringIO extends NamedBean {
014
015    /**
016     * Change the commanded value, which results in the relevant command(s)
017     * being sent to the hardware. The exception is thrown if there are problems
018     * communicating with the layout hardware.
019     *
020     * @param value the desired string value
021     * @throws jmri.JmriException general error when setting the value fails
022     */
023    void setCommandedStringValue(@Nonnull String value) throws JmriException;
024
025    /**
026     * Query the commanded string. This is a bound parameter, so you can also
027     * register a listener to be informed of changes.
028     *
029     * @return the string value
030     */
031    @Nonnull
032    String getCommandedStringValue();
033
034    /**
035     * Query the known string value. This is a bound parameter, so you can also
036     * register a listener to be informed of changes. A result is always
037     * returned; if no other feedback method is available, the commanded value
038     * will be used.
039     *
040     * @return the known string value
041     */
042    @Nonnull
043    default String getKnownStringValue() {
044        return getCommandedStringValue();
045    }
046
047    /**
048     * Get the maximum length of string that this StringIO can handle.
049     * @return the maximum length or 0 if arbitrary lengths are accepted.
050     */
051    default int getMaximumLength() {
052        return 0;
053    }
054
055    /**
056     * Request an update from the layout soft/hardware. May not even happen, and
057     * if it does it will happen later; listen for the result.
058     */
059    default void requestUpdateFromLayout() {
060    }
061
062}