001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.CheckReturnValue;
005import javax.annotation.Nonnull;
006
007/**
008 * Interface for controlling sensors.
009 *
010 * <hr>
011 * This file is part of JMRI.
012 * <p>
013 * JMRI is free software; you can redistribute it and/or modify it under the
014 * terms of version 2 of the GNU General Public License as published by the Free
015 * Software Foundation. See the "COPYING" file for a copy of this license.
016 * <p>
017 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
018 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
019 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
020 *
021 * @author Bob Jacobsen Copyright (C) 2001
022 */
023public interface SensorManager extends ProvidingManager<Sensor>, NameIncrementingManager {
024
025    /**
026     * Get the Sensor with the user name, then system name if needed; if that fails, create a
027     * new Sensor.
028     * If the name is a valid system name, it will be used for the new Sensor.
029     * Otherwise, the {@link Manager#makeSystemName} method will attempt to turn it
030     * into a valid system name.
031     * <p>This provides the same function as {@link ProvidingManager#provide}
032     * which has a more generic form.
033     *
034     * @param name User name, system name, or address which can be promoted to
035     *             system name
036     * @return Never null
037     * @throws IllegalArgumentException if Sensor doesn't already exist and the
038     *                                  manager cannot create the Sensor due to
039     *                                  an illegal name or name that can't
040     *                                  be parsed.
041     */
042    @Nonnull
043    Sensor provideSensor(@Nonnull String name) throws IllegalArgumentException;
044
045    /** {@inheritDoc} */
046    @Override
047    default Sensor provide(@Nonnull String name) throws IllegalArgumentException { return provideSensor(name); }
048
049    /**
050     * Get an existing Sensor or return null if it doesn't exist.
051     *
052     * Locates via user name, then system name if needed.
053     *
054     * @param name User name or system name to match
055     * @return null if no match found
056     */
057    @CheckReturnValue
058    @CheckForNull
059    Sensor getSensor(@Nonnull String name);
060
061    // to free resources when no longer used
062    @Override
063    void dispose();
064
065    /**
066     * Return a Sensor with the specified user or system name.
067     * Return Sensor by UserName else provide by SystemName.
068     * <p>
069     * Note that
070     * two calls with the same arguments will get the same instance; there is
071     * only one Sensor object representing a given physical turnout and
072     * therefore only one with a specific system or user name.
073     * <p>
074     * This will always return a valid object reference; a new object will be
075     * created if necessary. In that case:
076     * <ul>
077     * <li>If a null reference is given for user name, no user name will be
078     * associated with the Sensor object created; a valid system name must be
079     * provided
080     * <li>If both names are provided, the system name defines the hardware
081     * access of the desired sensor, and the user address is associated with it.
082     * The system name must be valid.
083     * </ul>
084     * Note that it is possible to make an inconsistent request if both
085     * addresses are provided, but the given values are associated with
086     * different objects. This is a problem, and we don't have a good solution
087     * except to issue warnings. This will mostly happen if you're creating
088     * Turnouts when you should be looking them up.
089     *
090     * @param systemName the desired system name
091     * @param userName   the desired user name
092     * @return requested Sensor object
093     * @throws IllegalArgumentException if cannot create the Sensor due to e.g.
094     *                                  an illegal name or name that can't be
095     *                                  parsed.
096     */
097    @Nonnull
098    Sensor newSensor(@Nonnull String systemName, @CheckForNull String userName) throws IllegalArgumentException;
099
100    /**
101     * Get an existing Sensor or return null if it doesn't exist.
102     *
103     * Locates via user name.
104     *
105     * @param name User name to match
106     * @return null if no match found
107     */
108    @CheckReturnValue
109    @CheckForNull
110    @Override
111    Sensor getByUserName(@Nonnull String name);
112
113    /**
114     * Get an existing Sensor or return null if it doesn't exist.
115     *
116     * Locates via system name
117     *
118     * @param name System name to match
119     * @return null if no match found
120     */
121    @CheckReturnValue
122    @CheckForNull
123    @Override
124    Sensor getBySystemName(@Nonnull String name);
125
126    /**
127     * Requests status of all layout sensors under this Sensor Manager. 
128     * <p>
129     * This method may be invoked whenever the status of sensors needs to be
130     * updated from the layout, for example, when an XML configuration file
131     * is read in.
132     * <p>
133     * This method only needs be implemented in system-specific Sensor Managers
134     * where readout of Sensor status from the layout is possible.
135     */
136    void updateAll();
137
138    /**
139     * Get a system name for a given hardware address and system prefix.
140     *
141     * @param curAddress desired hardware address
142     * @param prefix     system prefix used in system name
143     * @return the complete sensor system name for the prefix and current
144     *         address
145     * @throws jmri.JmriException if unable to create a system name for the
146     *                            given address, possibly due to invalid address
147     *                            format
148     */
149    @Nonnull
150    String createSystemName(@Nonnull String curAddress, @Nonnull String prefix) throws JmriException;
151
152    @CheckReturnValue
153    long getDefaultSensorDebounceGoingActive();
154
155    @CheckReturnValue
156    long getDefaultSensorDebounceGoingInActive();
157
158    void setDefaultSensorDebounceGoingActive(long timer);
159
160    void setDefaultSensorDebounceGoingInActive(long timer);
161
162    /**
163     * Do the sensor objects provided by this manager support configuring
164     * an internal pullup or pull down resistor?
165     *
166     * @return true if pull up/pull down configuration is supported.
167     */
168    boolean isPullResistanceConfigurable();
169
170    /**
171     * Provide a manager-specific tooltip for the Add new item beantable pane.
172     */
173    @Override
174    String getEntryToolTip();
175
176}