Interface LightManager
- All Superinterfaces:
Manager<Light>
,PropertyChangeProvider
,ProvidingManager<Light>
,SilenceablePropertyChangeProvider
,VetoableChangeProvider
- All Known Implementing Classes:
AbstractLightManager
,AcelaLightManager
,CbusLightManager
,DCCppLightManager
,InternalLightManager
,IpocsLightManager
,JMRIClientLightManager
,LnLightManager
,MqttLightManager
,NceLightManager
,OlcbLightManager
,ProxyLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,UsbLightManager
,XBeeLightManager
,XNetLightManager
public interface LightManager extends ProvidingManager<Light>
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, deprecatedManagerLogger, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXNG_ANALOG_ACTIONS, LOGIXNG_ANALOG_EXPRESSIONS, LOGIXNG_CONDITIONALNGS, LOGIXNG_DIGITAL_ACTIONS, LOGIXNG_DIGITAL_BOOLEAN_ACTIONS, LOGIXNG_DIGITAL_EXPRESSIONS, 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
Modifier and Type Method Description void
activateAllLights()
Activate the control mechanism for each Light controlled by this LightManager.boolean
allowMultipleAdditions(String systemName)
Test if possible to generate multiple lights given a numerical range to complete the system name.String
convertSystemNameToAlternate(String systemName)
Convert the system name to a normalized alternate name.String
createSystemName(String curAddress, String prefix)
Get a system name for a given hardware address and system prefix.void
dispose()
Free resources when no longer used.Light
getBySystemName(String s)
Locate a Light by its system name.Light
getByUserName(String s)
Locate a Light by its user name.Light
getLight(String name)
Get an existing Light or return null if it doesn't exist.String
getNextValidAddress(String curAddress, String prefix, boolean ignoreInitialExisting)
Get the Next valid hardware address.Light
newLight(String systemName, String userName)
Return a Light with the specified user or system name.default Light
provide(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(String name)
Get the Light with the user name, then system name if needed; if that fails, create a new Light.boolean
supportsVariableLights(String systemName)
Test if system in the given name can support a variable light.default boolean
validSystemNameConfig(String systemName)
Test if parameter is a valid system name for current configuration.Methods inherited from interface jmri.Manager
addDataListener, deleteBean, deregister, getBeanBySystemName, getBeanByUserName, getBeanTypeHandled, getBeanTypeHandled, getEntryToolTip, getKnownBeanProperties, getMemo, getNamedBean, getNamedBeanClass, getNamedBeanList, getNamedBeanSet, getObjectCount, getSubSystemNamePrefix, getSystemNameList, getSystemNamePrefix, getSystemPrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, makeSystemName, register, removeDataListener, setDataListenerMute, setPropertyChangesMuted, typeLetter, validateBadCharsInSystemNameFormat, validateIntegerSystemNameFormat, validateNmraAccessorySystemNameFormat, validateSystemNameFormat, validateSystemNameFormat, validateSystemNameFormatOnlyNumeric, validateSystemNamePrefix, validateTrimmedMin1NumberSystemNameFormat, validateTrimmedSystemNameFormat, validateUppercaseTrimmedSystemNameFormat, validSystemNameFormat
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 Details
-
provideLight
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:
IllegalArgumentException
-
provide
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:
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
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 String systemName, @CheckForNull String userName) throws IllegalArgumentExceptionReturn 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:
IllegalArgumentException
- if cannot create the Light due to e.g. an illegal name or name that can't be parsed.
-
getByUserName
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
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
Test if parameter is a valid system name for current configuration.- Parameters:
systemName
- the system name- Returns:
- true if valid; false otherwise
-
convertSystemNameToAlternate
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
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
-
allowMultipleAdditions
Test if possible to generate multiple lights given a numerical range to complete the system name.- Parameters:
systemName
- the system name- Returns:
- true if multiple lights can be created at once; false otherwise
-
getNextValidAddress
@Nonnull String getNextValidAddress(@Nonnull String curAddress, @Nonnull String prefix, boolean ignoreInitialExisting) throws JmriExceptionGet the Next valid hardware address. Used by the Turnout / Sensor / Reporter / Light Manager classes.System-specific methods may want to override getIncrement() rather than this one.
- Parameters:
curAddress
- the starting hardware address to get the next valid from.prefix
- system prefix, just system name, not type letter.ignoreInitialExisting
- false to return the starting address if it does not exist, else true to force an increment.- Returns:
- the next valid system name, excluding both system name prefix and type letter.
- Throws:
JmriException
- if unable to get the current / next address, or more than 10 next addresses in use.
-
createSystemName
@Nonnull String createSystemName(@Nonnull String curAddress, @Nonnull String prefix) throws JmriExceptionGet 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
-