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}