Package jmri

Interface TurnoutManager

    • 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, 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:
        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 interface ProvidingManager<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

      • 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.
        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:
        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, 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
                   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

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

      • 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