Package jmri.managers

Class ProxyIdTagManager

    • Method Detail

      • getXMLOrder

        public int getXMLOrder()
        Description copied from interface: Manager
        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.

      • isInitialised

        public boolean isInitialised()
        Determines if the manager has been initialized.
        Specified by:
        isInitialised in interface IdTagManager
        Returns:
        true if All IdTagManagers have initialised.

      • getIdTag

        @CheckForNull
public IdTag getIdTag​(@Nonnull
                      java.lang.String name)
        Locate via user name, then system name if needed.
        Specified by:
        getIdTag in interface IdTagManager
        Parameters:
        name - tag name being requested
        Returns:
        Null if nothing by that name exists

      • makeBean

        @Nonnull
protected IdTag makeBean​(Manager<IdTag> manager,
                         java.lang.String systemName,
                         java.lang.String userName)
                  throws java.lang.IllegalArgumentException
        Description copied from class: AbstractProvidingProxyManager
        Defer creation of the proper type to the subclass.
        Specified by:
        makeBean in class AbstractProvidingProxyManager<IdTag>
        Parameters:
        manager - the manager to invoke
        systemName - the system name
        userName - the user name
        Returns:
        a bean
        Throws:
        java.lang.IllegalArgumentException - if unable to make.

      • 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 user name, then 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:
        Never null under normal circumstances
        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.

      • newIdTag

        @Nonnull
public IdTag newIdTag​(@Nonnull
                      java.lang.String systemName,
                      java.lang.String userName)
               throws java.lang.IllegalArgumentException
        Get 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 light and therefore only one with a specific system or user name.

        This will always return a valid object reference for a valid request; 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 a null reference is given for the system name, a system name will _somehow_ be inferred from the user name. How this is done is system specific. Note: a future extension of this interface will add an exception to signal that this was not possible.
        • If both names are provided, the system name defines the hardware access of the desired turnout, and the user address is associated with it.
        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 IdTags 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.

      • getByTagID

        @CheckForNull
public IdTag getByTagID​(@Nonnull
                        java.lang.String tagID)
        Description copied from interface: IdTagManager
        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

      • getBeanTypeHandled

        @Nonnull
public java.lang.String getBeanTypeHandled​(boolean plural)
        Description copied from interface: Manager
        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.

      • setStateStored

        public void setStateStored​(boolean state)
        Description copied from interface: IdTagManager
        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()
        Description copied from interface: IdTagManager
        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)
        Description copied from interface: IdTagManager
        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()
        Description copied from interface: IdTagManager
        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)
        Description copied from interface: IdTagManager
        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