Package jmri.managers

Class DefaultIdTagManager

    • Method Detail

      • getXMLOrder

        public int getXMLOrder()
        Determine the order that types should be written when storing panel files. Uses one of the constants defined in this class.

        Yes, that's an overly-centralized methodology, but it works for now.

        Specified by:
        getXMLOrder in interface Manager<IdTag>
        Returns:
        write order for this Manager; larger is later.

      • registerSelf

        protected void registerSelf()
        By default, register this manager to store as configuration information. Override to change that. Don't want to store this information
        Overrides:
        registerSelf in class AbstractManager<IdTag>

      • provide

        @Nonnull
public IdTag 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: TurnoutManager.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<IdTag>
        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.

      • provideIdTag

        @Nonnull
public 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.
        Specified by:
        provideIdTag in interface IdTagManager
        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

        @CheckForNull
public 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
        Specified by:
        getIdTag in interface IdTagManager
        Parameters:
        name - tag name being requested
        Returns:
        null if no match found

      • getByTagID

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

      • createNewIdTag

        @Nonnull
protected IdTag createNewIdTag​(java.lang.String systemName,
                               java.lang.String userName)
                        throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException

      • newIdTag

        @Nonnull
public IdTag newIdTag​(@Nonnull
                      java.lang.String systemName,
                      @CheckForNull
                      java.lang.String userName)
               throws java.lang.IllegalArgumentException
        Provide ID Tag by UserName then SystemName, creates new IdTag if not found. 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.
        Specified by:
        newIdTag in interface IdTagManager
        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.

      • propertyChange

        public void propertyChange​(java.beans.PropertyChangeEvent e)
        The PropertyChangeListener interface in this class is intended to keep track of user name changes to individual NamedBeans. It is not completely implemented yet. In particular, listeners are not added to newly registered objects.
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener
        Overrides:
        propertyChange in class AbstractManager<IdTag>
        Parameters:
        e - the event

      • writeIdTagDetails

        public void writeIdTagDetails()
                       throws java.io.IOException
        Throws:
        java.io.IOException

      • setStateStored

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

      • isStateStored

        public boolean isStateStored()
        Determines if the state of known IdTags should be stored.
        Specified by:
        isStateStored in interface IdTagManager
        Returns:
        True to store state; False to discard state

      • setFastClockUsed

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

      • isFastClockUsed

        public boolean isFastClockUsed()
        Determines if fast clock times should be recorded for when a given IdTag was last seen.
        Specified by:
        isFastClockUsed in interface IdTagManager
        Returns:
        True to use the fast clock; False to use the system clock

      • getTagsForReporter

        @Nonnull
public 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.
        Specified by:
        getTagsForReporter in interface IdTagManager
        Parameters:
        reporter - Reporter to return list for
        threshold - Time threshold (in ms)
        Returns:
        List of matching IdTags

      • getBeanTypeHandled

        @Nonnull
public java.lang.String getBeanTypeHandled​(boolean plural)
        Get the user-readable name of the type of NamedBean handled by this manager.

        For instance, in the code where we are dealing with just a bean and a message that needs to be passed to the user or in a log.

        Specified by:
        getBeanTypeHandled in interface Manager<IdTag>
        Parameters:
        plural - true to return plural form of the type; false to return singular form
        Returns:
        a string of the bean type that the manager handles, eg Turnout, Sensor etc

      • getNamedBeanClass

        public java.lang.Class<IdTag> getNamedBeanClass()
        Get the class of NamedBean supported by this Manager. This should be the generic class used in the Manager's class declaration.
        Specified by:
        getNamedBeanClass in interface Manager<IdTag>
        Returns:
        the class supported by this Manager.