001package jmri;
002
003import javax.annotation.CheckReturnValue;
004
005/**
006 * Represent an analog I/O on the layout.
007 * 
008 * @author Daniel Bergqvist Copyright (C) 2018
009 */
010public interface AnalogIO extends NamedBean {
011
012    /**
013     * Is the value an absolute value or a relative value?
014     * In both cases, AnalogIO.getMin() and AnalogIO.getMax() tells the
015     * limits of the value.
016     */
017    enum AbsoluteOrRelative {
018        
019        ABSOLUTE(Bundle.getMessage("AnalogIO_Absolute")),
020        RELATIVE(Bundle.getMessage("AnalogIO_Relative"));
021        
022        private final String _str;
023        
024        private AbsoluteOrRelative(String str) {
025            _str = str;
026        }
027        
028        @CheckReturnValue
029        @Override
030        public String toString() {
031            return _str;
032        }
033    }
034    
035    /**
036     * Show whether the analog value is stable.
037     * 
038     * @return true if the analog value is stable
039     */
040    @CheckReturnValue
041    default boolean isConsistentValue() {
042        return true;
043    }
044    
045    /**
046     * Change the commanded value, which results in the relevant command(s)
047     * being sent to the hardware. The exception is thrown if there are problems
048     * communicating with the layout hardware.
049     * <p>
050     * The value must be a valid number, not a NaN or infinity number.
051     *
052     * @param value the desired analog value
053     * @throws jmri.JmriException general error when setting the value fails
054     * @throws IllegalArgumentException if the value is Double.NaN,
055     *                                  Double.NEGATIVE_INFINITY or
056     *                                  Double.POSITIVE_INFINITY
057     */
058    void setCommandedAnalogValue(double value) throws JmriException;
059
060    /**
061     * Query the commanded value. This is a bound parameter, so you can also
062     * register a listener to be informed of changes.
063     * <p>
064     * The result must be a valid number, not a NaN or infinity number.
065     *
066     * @return the analog value
067     */
068    @CheckReturnValue
069    double getCommandedAnalogValue();
070    
071    /**
072     * Query the known analog value. This is a bound parameter, so you can also
073     * register a listener to be informed of changes. A result is always
074     * returned; if no other feedback method is available, the commanded value
075     * will be used.
076     * <p>
077     * The result must be a valid number, not a NaN or infinity number.
078     *
079     * @return the known analog value
080     */
081    @CheckReturnValue
082    default double getKnownAnalogValue() {
083        return getCommandedAnalogValue();
084    }
085    
086    /**
087     * Provide generic access to internal state.
088     * <p>
089     * This generally shouldn't be used by Java code; use the class-specific
090     * form instead (setCommandedAnalogValue). This is provided to
091     * make scripts access easier to read.
092     *
093     * @param value the analog value
094     * @throws JmriException general error when setting the state fails
095     */
096    @InvokeOnLayoutThread
097    void setState(double value) throws JmriException;
098
099    /**
100     * Provide generic access to internal state.
101     * <p>
102     * This generally shouldn't be used by Java code; use the class-specific
103     * form instead (getCommandedAnalogValue). This is provided to
104     * make scripts easier to read.
105     * 
106     * @param v only used to select this method which returns an analog value.
107     *          It's recommended to use 0.0 as the parameter.
108     * @return the state
109     */
110    @CheckReturnValue
111    double getState(double v);
112
113    /**
114     * Get the minimum value of this AnalogIO.
115     * @return minimum value.
116     */
117    @CheckReturnValue
118    double getMin();
119    
120    /**
121     * Get the maximum value of this AnalogIO.
122     * @return maximum value.
123     */
124    @CheckReturnValue
125    double getMax();
126    
127    /**
128     * Get the resolution of this AnalogIO.
129     * @return analog resolution.
130     */
131    @CheckReturnValue
132    double getResolution();
133
134    /**
135     * Is this AnalogIO absolute or relative?
136     * @return if absolute or relative.
137     */
138    @CheckReturnValue
139    AbsoluteOrRelative getAbsoluteOrRelative();
140
141    /**
142     * Request an update from the layout soft/hardware. May not even happen, and
143     * if it does it will happen later; listen for the result.
144     */
145    default void requestUpdateFromLayout() {
146    }
147
148}