Package jmri

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>
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

  • Method Details

    • provideTurnout

      @Nonnull Turnout provideTurnout​(@Nonnull String name) throws 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, the Manager.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

      default Turnout provide​(@Nonnull String name) throws 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 interface ProvidingManager<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

      @CheckForNull Turnout getTurnout​(@Nonnull 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 String systemName)
      Get the Turnout with the given system name or null if no instance already exists.
      Specified by:
      getBySystemName in interface Manager<Turnout>
      Parameters:
      systemName - the system name
      Returns:
      requested Turnout object or null if none exists

    • getByUserName

      @CheckForNull Turnout getByUserName​(@Nonnull String userName)
      Get the Turnout with the given user name or null if no instance already exists.
      Specified by:
      getByUserName in interface Manager<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 IllegalArgumentException
      Return a Turnout with the specified system and user names. 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.
      Note that it is possible to make an inconsistent request if both addresses are provided, but the given values are associated with different objects. This is a problem, and we don't have a good solution except to issue warnings. This will mostly happen if you're creating Turnouts when you should be looking them up.
      Parameters:
      systemName - the system name
      userName - 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

      @Nonnull 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 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 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 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 String systemName)
      Determine if the manager supports multiple control bits, as askNumControlBits(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 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 String systemName)
      Determine if the manager supports the handling of pulsed and steady state control as the askControlType(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

      boolean allowMultipleAdditions​(@Nonnull String systemName)
      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 JmriException
      Deprecated.
      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 name
      curAddress - 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 JmriException
      Get 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, 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

      String createSystemName​(@Nonnull String curAddress, @Nonnull String prefix) throws JmriException
      Get a system name for a given hardware address and system prefix.
      Parameters:
      curAddress - desired hardware address
      prefix - 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 String speed) throws JmriException
      Throws:
      JmriException

    • setDefaultThrownSpeed

      void setDefaultThrownSpeed​(@Nonnull String speed) throws JmriException
      Throws:
      JmriException

    • getDefaultThrownSpeed

      String getDefaultThrownSpeed()

    • getDefaultClosedSpeed

      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 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