Interface LightManager
-
- All Superinterfaces:
Manager<Light>
,NameIncrementingManager
,PropertyChangeProvider
,ProvidingManager<Light>
,SilenceablePropertyChangeProvider
,VetoableChangeProvider
- All Known Implementing Classes:
AbstractLightManager
,AcelaLightManager
,BiDiBLightManager
,CbusLightManager
,DCCppLightManager
,InternalLightManager
,IpocsLightManager
,JMRIClientLightManager
,LnLightManager
,MqttLightManager
,NceLightManager
,OlcbLightManager
,ProxyLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,UsbLightManager
,XBeeLightManager
,XNetLightManager
public interface LightManager extends ProvidingManager<Light>, NameIncrementingManager
Interface for obtaining Lights.This doesn't have a "new" method, as Lights are separately implemented, instead of being system-specific.
Based on SignalHeadManager.java
This file is part of JMRI.JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.Manager
Manager.ManagerDataEvent<E extends NamedBean>, Manager.ManagerDataListener<E extends NamedBean>, Manager.NameValidity
-
-
Field Summary
-
Fields inherited from interface jmri.Manager
ANALOGIOS, AUDIO, BLOCKBOSS, BLOCKS, CONDITIONALS, CTCDATA, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXNG_ANALOG_ACTIONS, LOGIXNG_ANALOG_EXPRESSIONS, LOGIXNG_CONDITIONALNGS, LOGIXNG_DIGITAL_ACTIONS, LOGIXNG_DIGITAL_BOOLEAN_ACTIONS, LOGIXNG_DIGITAL_EXPRESSIONS, LOGIXNG_GLOBAL_VARIABLES, LOGIXNG_MODULES, LOGIXNG_STRING_ACTIONS, LOGIXNG_STRING_EXPRESSIONS, LOGIXNG_TABLES, LOGIXNGS, LOGIXS, MEMORIES, METERFRAMES, METERS, OBLOCKS, PANELFILES, REPORTERS, ROUTES, SECTIONS, SENSORGROUPS, SENSORS, SIGNALGROUPS, SIGNALHEADS, SIGNALMASTLOGICS, SIGNALMASTS, STRINGIOS, TIMEBASE, TRANSITS, TURNOUTS, WARRANTS
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
activateAllLights()
Activate the control mechanism for each Light controlled by this LightManager.java.lang.String
convertSystemNameToAlternate(java.lang.String systemName)
Convert the system name to a normalized alternate name.java.lang.String
createSystemName(java.lang.String curAddress, java.lang.String prefix)
Get a system name for a given hardware address and system prefix.void
dispose()
Free resources when no longer used.Light
getBySystemName(java.lang.String s)
Locate a Light by its system name.Light
getByUserName(java.lang.String s)
Locate a Light by its user name.Light
getLight(java.lang.String name)
Get an existing Light or return null if it doesn't exist.Light
newLight(java.lang.String systemName, java.lang.String userName)
Return a Light with the specified user or system name.default Light
provide(java.lang.String name)
Get an existing instance via user name, then system name; if no matching instance is found, create a new NameBean from the system name.Light
provideLight(java.lang.String name)
Get the Light with the user name, then system name if needed; if that fails, create a new Light.boolean
supportsVariableLights(java.lang.String systemName)
Test if system in the given name can support a variable light.default boolean
validSystemNameConfig(java.lang.String systemName)
Test if parameter is a valid system name for current configuration.-
Methods inherited from interface jmri.Manager
addDataListener, deleteBean, deregister, getBeanTypeHandled, getBeanTypeHandled, getEntryToolTip, getKnownBeanProperties, getMemo, getNamedBean, getNamedBeanClass, getNamedBeanSet, getObjectCount, getSubSystemNamePrefix, getSystemNamePrefix, getSystemPrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, makeSystemName, register, removeDataListener, setDataListenerMute, typeLetter, validateBadCharsInSystemNameFormat, validateIntegerSystemNameFormat, validateNmraAccessorySystemNameFormat, validateSystemNameFormat, validateSystemNameFormat, validateSystemNameFormatOnlyNumeric, validateSystemNamePrefix, validateTrimmedMin1NumberSystemNameFormat, validateTrimmedSystemNameFormat, validateUppercaseTrimmedSystemNameFormat, validSystemNameFormat
-
Methods inherited from interface jmri.NameIncrementingManager
allowMultipleAdditions, getNextValidSystemName
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
Methods inherited from interface jmri.beans.SilenceablePropertyChangeProvider
setPropertyChangesSilenced
-
Methods inherited from interface jmri.beans.VetoableChangeProvider
addVetoableChangeListener, addVetoableChangeListener, getVetoableChangeListeners, getVetoableChangeListeners, removeVetoableChangeListener, removeVetoableChangeListener
-
-
-
-
Method Detail
-
provideLight
@Nonnull Light provideLight(@Nonnull java.lang.String name) throws java.lang.IllegalArgumentException
Get the Light with the user name, then system name if needed; if that fails, create a new Light. If the name is a valid system name, it will be used for the new Light. Otherwise, theManager.makeSystemName(java.lang.String)
method will attempt to turn it into a valid system name.This provides the same function as
ProvidingManager.provide(java.lang.String)
which has a more generic form.- Parameters:
name
- User name, system name, or address which can be promoted to system name- Returns:
- Never null under normal circumstances
- Throws:
java.lang.IllegalArgumentException
-
provide
@Nonnull default Light provide(@Nonnull java.lang.String name) throws java.lang.IllegalArgumentException
Get an existing instance via user name, then system name; if no matching instance is found, create a new NameBean from the system name.If the name is a valid system name, it will be used for the new NamedBean. Otherwise, the
Manager.makeSystemName(java.lang.String)
method will attempt to turn it into a valid system name which the manager will attempt to use. If that fails, an exception is thrown.This is similar to the specific methods found in certain type-specific managers:
TurnoutManager.provideTurnout(java.lang.String)
,SensorManager.provideSensor(java.lang.String)
, et al. Those might be more mnemonic; this one is more generic. Neither is preferred nor deprecated; use your choice.- Specified by:
provide
in interfaceProvidingManager<Light>
- Parameters:
name
- User name, system name, or address which can be promoted to system name- Returns:
- Never null
- Throws:
java.lang.IllegalArgumentException
- if NamedBean doesn't already exist and the manager cannot create it due to an illegal name or name that can't be parsed.
-
dispose
void dispose()
Free resources when no longer used. Specifically, remove all references to and from this object, so it can be garbage-collected.
-
getLight
@CheckReturnValue @CheckForNull Light getLight(@Nonnull java.lang.String name)
Get an existing Light or return null if it doesn't exist.Locates via user name, then system name if needed.
- Parameters:
name
- User name, system name, or address which can be promoted to system name- Returns:
- Light, or null if no existing Light.
-
newLight
@Nonnull Light newLight(@Nonnull java.lang.String systemName, @CheckForNull java.lang.String userName) throws java.lang.IllegalArgumentException
Return a Light with the specified user or system name. Lookup Light by UserName, then Provide New Light by SystemName. Note that two calls with the same arguments will get the same instance; there is only one Light object representing a given physical Light and therefore only one with a specific system or user name.This will always return a valid object reference; a new object will be created if necessary. In that case:
- If a null reference is given for user name, no user name will be associated with the Light object created; a valid system name must be provided
- If both names are provided, the system name defines the hardware access of the desired sensor, and the user address is associated with it. The system name must be valid.
- Parameters:
systemName
- the desired system nameuserName
- the desired user name- Returns:
- requested Light object (never null)
- Throws:
java.lang.IllegalArgumentException
- if cannot create the Light due to e.g. an illegal name or name that can't be parsed.
-
getByUserName
@CheckReturnValue @CheckForNull Light getByUserName(@Nonnull java.lang.String s)
Locate a Light by its user name.- Specified by:
getByUserName
in interfaceManager<Light>
- Parameters:
s
- the user name- Returns:
- the light or null if not found
-
getBySystemName
@CheckReturnValue @CheckForNull Light getBySystemName(@Nonnull java.lang.String s)
Locate a Light by its system name.- Specified by:
getBySystemName
in interfaceManager<Light>
- Parameters:
s
- the system name- Returns:
- the light or null if not found
-
validSystemNameConfig
@CheckReturnValue default boolean validSystemNameConfig(@Nonnull java.lang.String systemName)
Test if parameter is a valid system name for current configuration.- Parameters:
systemName
- the system name- Returns:
- true if valid; false otherwise
-
convertSystemNameToAlternate
@CheckReturnValue @Nonnull java.lang.String convertSystemNameToAlternate(@Nonnull java.lang.String systemName)
Convert the system name to a normalized alternate name.This routine is to allow testing to ensure that two Lights with alternate names that refer to the same output bit are not created.
This routine is implemented in AbstractLightManager to return "". If a system implementation has alternate names, the system specific Light Manager should override this routine and supply the alternate name.
- Parameters:
systemName
- the system name to convert- Returns:
- an alternate name
-
activateAllLights
void activateAllLights()
Activate the control mechanism for each Light controlled by this LightManager. Note that some Lights don't require any activation. The activateLight method in AbstractLight.java determines what needs to be done for each Light.
-
supportsVariableLights
@CheckReturnValue boolean supportsVariableLights(@Nonnull java.lang.String systemName)
Test if system in the given name can support a variable light.- Parameters:
systemName
- the system name- Returns:
- true if variable lights are supported; false otherwise
-
createSystemName
@Nonnull java.lang.String createSystemName(@Nonnull java.lang.String curAddress, @Nonnull java.lang.String prefix) throws JmriException
Get a system name for a given hardware address and system prefix.- Parameters:
curAddress
- desired hardware addressprefix
- system prefix used in system name, excluding Bean type-letter.- Returns:
- the complete Light system name for the prefix and current address
- Throws:
JmriException
- if unable to create a system name for the given address, possibly due to invalid address format
-
-