Package jmri

Interface IdTagManager

  • All Superinterfaces:
    Manager<IdTag>, PropertyChangeProvider, ProvidingManager<IdTag>, SilenceablePropertyChangeProvider, VetoableChangeProvider
    All Known Subinterfaces:
    RailComManager
    All Known Implementing Classes:
    DefaultIdTagManager, DefaultRailComManager, ProxyIdTagManager, TranspondingTagManager
    public interface IdTagManager
extends ProvidingManager<IdTag>
    Locate an IdTag object representing a specific IdTag.

    IdTag objects are obtained from an IdTagManager, which in turn is generally located from the InstanceManager. A typical call sequence might be: 

     IdTag tag = InstanceManager.idTagManagerInstance().newIdTag(null,"23");

    Each IdTag 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 AbstractIdTagManager class, which can form the basis for a system-specific implementation.

    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.

    Since:
    2.11.4
    See Also:
    IdTag, InstanceManager

    • Method Detail

      • provideIdTag

        @Nonnull
IdTag provideIdTag​(@Nonnull
                   java.lang.String name)
            throws java.lang.IllegalArgumentException
        Locate via tag ID, then user name, and finally system name if needed. If that fails, create a new IdTag. If the name is a valid system name, it will be used for the new IdTag. Otherwise, the makeSystemName method will attempt to turn it into a valid system name.
        Parameters:
        name - Tag ID, user name, system name, or address which can be promoted to system name
        Returns:
        A tag ID
        Throws:
        java.lang.IllegalArgumentException - if IdTag doesn't already exist and the manager cannot create the IdTag due to an illegal name or name that can't be parsed.

      • getIdTag

        @CheckReturnValue
@CheckForNull
IdTag getIdTag​(@Nonnull
               java.lang.String name)
        Locate via tag ID, then by user name, and finally system name if needed. If that fails, return null
        Parameters:
        name - tag name being requested
        Returns:
        null if no match found

      • getByTagID

        @CheckReturnValue
@CheckForNull
IdTag getByTagID​(@Nonnull
                 java.lang.String tagID)
        Locate an instance based on a tag ID. Returns null if no instance already exists.
        Parameters:
        tagID - tag ID being requested
        Returns:
        requested IdTag object or null if none exists

      • newIdTag

        @Nonnull
IdTag newIdTag​(@Nonnull
               java.lang.String systemName,
               @CheckForNull
               java.lang.String userName)
        throws java.lang.IllegalArgumentException
        Return an instance with the specified system and user names. Note that two calls with the same arguments will get the same instance; there is only one IdTag object representing a given physical IdTag 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 IdTag object created; a valid system name must be provided
        • If both are provided, the system name defines the hardware access of the desired IdTag, 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 RfidTags when you should be looking them up.
        Parameters:
        systemName - the system name
        userName - the user name
        Returns:
        requested IdTag object (never null)
        Throws:
        java.lang.IllegalArgumentException - if cannot create the IdTag due to e.g. an illegal name or name that can't be parsed.

      • getTagsForReporter

        @CheckReturnValue
@Nonnull
java.util.List<IdTag> getTagsForReporter​(@Nonnull
                                         Reporter reporter,
                                         long threshold)
        Get a list of all IdTags seen by a specified Reporter within a specific time threshold from the most recently seen.
        Parameters:
        reporter - Reporter to return list for
        threshold - Time threshold (in ms)
        Returns:
        List of matching IdTags

      • setStateStored

        void setStateStored​(boolean state)
        Define if the manager should persist details of when and where all known IdTags were seen.
        Parameters:
        state - True to store; False to omit

      • isStateStored

        @CheckReturnValue
boolean isStateStored()
        Determines if the state of known IdTags should be stored.
        Returns:
        True to store state; False to discard state

      • setFastClockUsed

        void setFastClockUsed​(boolean fastClock)
        Define if the manager should use the fast clock when setting the times when a given IdTag was last seen.
        Parameters:
        fastClock - True to use the fast clock; False to use the system clock

      • isFastClockUsed

        @CheckReturnValue
boolean isFastClockUsed()
        Determines if fast clock times should be recorded for when a given IdTag was last seen.
        Returns:
        True to use the fast clock; False to use the system clock

      • init

        void init()
        Perform initialization.