Interface TurnoutManager
- All Superinterfaces:
Manager<Turnout>
,PropertyChangeProvider
,ProvidingManager<Turnout>
,SilenceablePropertyChangeProvider
,VetoableChangeProvider
- All Known Implementing Classes:
AbstractTurnoutManager
,AcelaTurnoutManager
,CbusTurnoutManager
,DCCppTurnoutManager
,EasyDccTurnoutManager
,EcosTurnoutManager
,EliteXNetTurnoutManager
,InternalTurnoutManager
,IpocsTurnoutManager
,JMRIClientTurnoutManager
,LnTurnoutManager
,MarklinTurnoutManager
,MqttTurnoutManager
,MrcTurnoutManager
,Mx1TurnoutManager
,NceTurnoutManager
,OlcbTurnoutManager
,ProxyTurnoutManager
,RaspberryPiTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SprogTurnoutManager
,SRCPTurnoutManager
,TamsTurnoutManager
,XBeeTurnoutManager
,XNetTurnoutManager
,XpaTurnoutManager
,Z21XNetTurnoutManager
,ZTC611XNetTurnoutManager
public interface TurnoutManager extends ProvidingManager<Turnout>
Turnout objects are obtained from a TurnoutManager, which in turn is generally located from the InstanceManager. A typical call sequence might be:
Turnout turnout = InstanceManager.turnoutManagerInstance().provideTurnout("23");
Each turnout has a two names. The "user" name is entirely free form, and can be used for any purpose. The "system" name is provided by the system-specific implementations, and provides a unique mapping to the layout control system (for example LocoNet or NCE) and address within that system.
Much of the book-keeping is implemented in the AbstractTurnoutManager class, which can form the basis for a system-specific implementation.
A sample use of the TurnoutManager interface can be seen in the jmri.jmrit.simpleturnoutctrl.SimpleTurnoutCtrlFrame class, which provides a simple GUI for controlling a single turnout.
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.
- See Also:
Turnout
,InstanceManager
,SimpleTurnoutCtrlFrame
-
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 boolean
allowMultipleAdditions(String systemName)
Determines if it is possible to add a range of turnouts in numerical order.int
askControlType(String systemName)
Get, from the user, the type of output to be used bits to control a turnout.int
askNumControlBits(String systemName)
Get, from the user, the number of addressed bits used to control a turnout.String
createSystemName(String curAddress, String prefix)
Get a system name for a given hardware address and system prefix.Turnout
getBySystemName(String systemName)
Get the Turnout with the given system name or null if no instance already exists.Turnout
getByUserName(String userName)
Get the Turnout with the given user name or null if no instance already exists.String
getClosedText()
Get text to be used for the Turnout.CLOSED state in user communication.String
getDefaultClosedSpeed()
String
getDefaultThrownSpeed()
String
getNextValidAddress(String curAddress, String prefix)
Deprecated.since 4.21.3; use #getNextValidAddress(String, String, boolean) instead.String
getNextValidAddress(String curAddress, String prefix, boolean ignoreInitialExisting)
Get the Next valid Turnout address.int
getOutputInterval()
Get the Interval (in ms) to wait between output commands.String
getThrownText()
Get text to be used for the Turnout.THROWN state in user communication.Turnout
getTurnout(String name)
Get an existing Turnout or return null if it doesn't exist.String[]
getValidOperationTypes()
Get a list of the valid TurnoutOperation subtypes for use with turnouts of this system.boolean
isControlTypeSupported(String systemName)
Determine if the manager supports the handling of pulsed and steady state control as theaskControlType(java.lang.String)
will always return a value even if it is not supported.boolean
isNumControlBitsSupported(String systemName)
Determine if the manager supports multiple control bits, asaskNumControlBits(java.lang.String)
will always return a value even if it is not supported.Turnout
newTurnout(String systemName, String userName)
Return a Turnout with the specified system and user names.LocalDateTime
outputIntervalEnds()
Get end time of latest OutputInterval, calculated from the current time.default Turnout
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.Turnout
provideTurnout(String name)
Get the Turnout with the user name, then system name if needed; if that fails, create a new Turnout.void
setDefaultClosedSpeed(String speed)
void
setDefaultThrownSpeed(String speed)
void
setOutputInterval(int newInterval)
Set the Interval (in ms) to wait between output commands.Methods inherited from interface jmri.Manager
addDataListener, deleteBean, deregister, dispose, 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
-
provideTurnout
Get the Turnout with the user name, then system name if needed; if that fails, create a new Turnout. If the name is a valid system name, it will be used for the new Turnout. 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
- Throws:
IllegalArgumentException
- if Turnout doesn't already exist and the manager cannot create the Turnout due to an illegal name or name that can't be parsed.
-
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:
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<Turnout>
- 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.
-
getTurnout
Get an existing Turnout or return null if it doesn't exist. Locates via user name, then system name if needed.- Parameters:
name
- User name or system name to match- Returns:
- null if no match found
-
getBySystemName
Get the Turnout with the given system name or null if no instance already exists.- Specified by:
getBySystemName
in interfaceManager<Turnout>
- Parameters:
systemName
- the system name- Returns:
- requested Turnout object or null if none exists
-
getByUserName
Get the Turnout with the given user name or null if no instance already exists.- Specified by:
getByUserName
in interfaceManager<Turnout>
- Parameters:
userName
- the user name- Returns:
- requested Turnout object or null if none exists
-
newTurnout
@Nonnull Turnout newTurnout(@Nonnull String systemName, @CheckForNull String userName) throws IllegalArgumentExceptionReturn a Turnout with the specified system and user names. Lookup by UserName then provide by System Name.Note that two calls with the same arguments will get the same instance; there is only one Turnout object representing a given physical turnout 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 Turnout object created; a valid system name must be provided
- If both names are provided, the system name defines the hardware access of the desired turnout, and the user address is associated with it. The system name must be valid.
- Parameters:
systemName
- the system nameuserName
- the user name (optional)- Returns:
- requested Turnout object, newly created if needed
- Throws:
IllegalArgumentException
- if cannot create the Turnout; likely due to an illegal name or name that cannot be parsed
-
getClosedText
Get text to be used for the Turnout.CLOSED state in user communication. Allows text other than "CLOSED" to be used with certain hardware system to represent the Turnout.CLOSED state.- Returns:
- the textual representation of
Turnout.CLOSED
-
getThrownText
Get text to be used for the Turnout.THROWN state in user communication. Allows text other than "THROWN" to be use with certain hardware system to represent the Turnout.THROWN state.- Returns:
- the textual representation of
Turnout.THROWN
-
getValidOperationTypes
Get a list of the valid TurnoutOperation subtypes for use with turnouts of this system.- Returns:
- a list of subtypes or an empty list if turnout operations are not supported
-
askNumControlBits
Get, from the user, the number of addressed bits used to control a turnout. Normally this is 1, and the default routine returns one automatically. Turnout Managers for systems that can handle multiple control bits should override this method with one which asks the user to specify the number of control bits. If the user specifies more than one control bit, this method should check if the additional bits are available (not assigned to another object). If the bits are not available, this method should return 0 for number of control bits, after informing the user of the problem.- Parameters:
systemName
- the turnout system name- Returns:
- the bit length for turnout control
-
isNumControlBitsSupported
Determine if the manager supports multiple control bits, asaskNumControlBits(java.lang.String)
will always return a value even if it is not supported.- Parameters:
systemName
- the turnout system name- Returns:
- true if manager supports multiple control bits for the turnout; false otherwise
-
askControlType
Get, from the user, the type of output to be used bits to control a turnout. Normally this is 0 for 'steady state' control, and the default routine returns 0 automatically. Turnout Managers for systems that can handle pulsed control as well as steady state control should override this method with one which asks the user to specify the type of control to be used. The routine should return 0 for 'steady state' control, or n for 'pulsed' control, where n specifies the duration of the pulse (normally in seconds).- Parameters:
systemName
- the turnout system name- Returns:
- 0 for steady state or the number of seconds for a pulse control
-
isControlTypeSupported
Determine if the manager supports the handling of pulsed and steady state control as theaskControlType(java.lang.String)
will always return a value even if it is not supported.- Parameters:
systemName
- the turnout system name- Returns:
- true if manager supports the control type returned by
askControlType(java.lang.String)
; false otherwise
-
allowMultipleAdditions
Determines if it is possible to add a range of turnouts in numerical order.- Parameters:
systemName
- the starting turnout system name; ignored in all known implementations- Returns:
- true if a range of turnouts can be added; false otherwise
-
getNextValidAddress
@Deprecated String getNextValidAddress(@Nonnull String curAddress, @Nonnull String prefix) throws JmriExceptionDeprecated.since 4.21.3; use #getNextValidAddress(String, String, boolean) instead.Get the next valid address.Determine if the address supplied is valid and free. If not then it shall return the next free valid address up to a maximum of 10 addresses away from the initial address. Used when adding add a range of Turnouts.
- Parameters:
prefix
- System prefix used in system namecurAddress
- desired hardware address- Returns:
- the next available address or null if next 10 addresses unavailable.
- Throws:
JmriException
- if unable to provide a turnout at the desired address due to invalid format for the current address or other reasons.
-
getNextValidAddress
@Nonnull String getNextValidAddress(@Nonnull String curAddress, @Nonnull String prefix, boolean ignoreInitialExisting) throws JmriExceptionGet the Next valid Turnout address.- 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 not already in use, 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
Get a system name for a given hardware address and system prefix.- Parameters:
curAddress
- desired hardware addressprefix
- system prefix used in system name- Returns:
- the complete turnout 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
-
setDefaultClosedSpeed
- Throws:
JmriException
-
setDefaultThrownSpeed
- Throws:
JmriException
-
getDefaultThrownSpeed
-
getDefaultClosedSpeed
-
getOutputInterval
int getOutputInterval()Get the Interval (in ms) to wait between output commands. Configured in AdapterConfig, stored in memo.- Returns:
- the (Turnout) Output Interval in milliseconds
-
setOutputInterval
Set the Interval (in ms) to wait between output commands.- Parameters:
newInterval
- the new Output Interval in Milliseconds
-
outputIntervalEnds
Get end time of latest OutputInterval, calculated from the current time.- Returns:
- end time in milliseconds or current time if no interval was set or timer has completed
-