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 Details

    • provideIdTag

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

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

      Locate an instance based on a system name. Returns null if no instance already exists.
      Specified by:
      getBySystemName in interface Manager<IdTag>
      Parameters:
      systemName - system name being requested
      Returns:
      requested IdTag object or null if none exists
    • getByUserName

      Locate an instance based on a user name. Returns null if no instance already exists.
      Specified by:
      getByUserName in interface Manager<IdTag>
      Parameters:
      userName - user name being requested
      Returns:
      requested IdTag object or null if none exists
    • getByTagID

      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

      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:
      IllegalArgumentException - if cannot create the IdTag due to e.g. an illegal name or name that can't be parsed.
    • getTagsForReporter

      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 (can be null)
      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

      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

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

      Determines if the manager has been initialized.
      Returns:
      state of initialization