Interface TurnoutManager
-
- All Superinterfaces:
Manager<Turnout>
,NameIncrementingManager
,PropertyChangeProvider
,ProvidingManager<Turnout>
,SilenceablePropertyChangeProvider
,VetoableChangeProvider
- All Known Implementing Classes:
AbstractTurnoutManager
,AcelaTurnoutManager
,BiDiBTurnoutManager
,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>, NameIncrementingManager
Locate a Turnout object representing some specific turnout on the layout.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, 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 int
askControlType(java.lang.String systemName)
Get, from the user, the type of output to be used bits to control a turnout.int
askNumControlBits(java.lang.String systemName)
Get, from the user, the number of addressed bits used to control a turnout.java.lang.String
createSystemName(java.lang.String curAddress, java.lang.String prefix)
Get a system name for a given hardware address and system prefix.Turnout
getBySystemName(java.lang.String systemName)
Get the Turnout with the given system name or null if no instance already exists.Turnout
getByUserName(java.lang.String userName)
Get the Turnout with the given user name or null if no instance already exists.java.lang.String
getClosedText()
Get text to be used for the Turnout.CLOSED state in user communication.java.lang.String
getDefaultClosedSpeed()
java.lang.String
getDefaultThrownSpeed()
int
getOutputInterval()
Get the Interval (in ms) to wait between output commands.java.lang.String
getThrownText()
Get text to be used for the Turnout.THROWN state in user communication.Turnout
getTurnout(java.lang.String name)
Get an existing Turnout or return null if it doesn't exist.java.lang.String[]
getValidOperationTypes()
Get a list of the valid TurnoutOperation subtypes for use with turnouts of this system.boolean
isControlTypeSupported(java.lang.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(java.lang.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(java.lang.String systemName, java.lang.String userName)
Return a Turnout with the specified system and user names.java.time.LocalDateTime
outputIntervalEnds()
Get end time of latest OutputInterval, calculated from the current time.default Turnout
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.Turnout
provideTurnout(java.lang.String name)
Get the Turnout with the user name, then system name if needed; if that fails, create a new Turnout.void
setDefaultClosedSpeed(java.lang.String speed)
void
setDefaultThrownSpeed(java.lang.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, 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
-
provideTurnout
@Nonnull Turnout provideTurnout(@Nonnull java.lang.String name) throws java.lang.IllegalArgumentException
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:
java.lang.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
@Nonnull default Turnout 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:
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:
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.
-
getTurnout
@CheckForNull Turnout getTurnout(@Nonnull java.lang.String name)
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
@CheckForNull Turnout getBySystemName(@Nonnull java.lang.String systemName)
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
@CheckForNull Turnout getByUserName(@Nonnull java.lang.String userName)
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 java.lang.String systemName, @CheckForNull java.lang.String userName) throws java.lang.IllegalArgumentException
Return 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:
java.lang.IllegalArgumentException
- if cannot create the Turnout; likely due to an illegal name or name that cannot be parsed
-
getClosedText
@Nonnull java.lang.String 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
@Nonnull java.lang.String 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
@Nonnull java.lang.String[] 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
int askNumControlBits(@Nonnull java.lang.String systemName)
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
boolean isNumControlBitsSupported(@Nonnull java.lang.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.- Parameters:
systemName
- the turnout system name- Returns:
- true if manager supports multiple control bits for the turnout; false otherwise
-
askControlType
int askControlType(@Nonnull java.lang.String systemName)
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
boolean isControlTypeSupported(@Nonnull java.lang.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.- Parameters:
systemName
- the turnout system name- Returns:
- true if manager supports the control type returned by
askControlType(java.lang.String)
; false otherwise
-
createSystemName
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- 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
void setDefaultClosedSpeed(@Nonnull java.lang.String speed) throws JmriException
- Throws:
JmriException
-
setDefaultThrownSpeed
void setDefaultThrownSpeed(@Nonnull java.lang.String speed) throws JmriException
- Throws:
JmriException
-
getDefaultThrownSpeed
java.lang.String getDefaultThrownSpeed()
-
getDefaultClosedSpeed
java.lang.String 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
void setOutputInterval(int newInterval)
Set the Interval (in ms) to wait between output commands.- Parameters:
newInterval
- the new Output Interval in Milliseconds
-
outputIntervalEnds
@Nonnull java.time.LocalDateTime 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
-
-