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
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.Manager
Manager.ManagerDataEvent<E extends NamedBean>, Manager.ManagerDataListener<E extends NamedBean>, Manager.NameValidity
-
-
Field Summary
-
Fields inherited from interface jmri.Manager
ANALOGIOS, AUDIO, BLOCKBOSS, BLOCKS, CONDITIONALS, CTCDATA, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXNG_ANALOG_ACTIONS, LOGIXNG_ANALOG_EXPRESSIONS, LOGIXNG_CONDITIONALNGS, LOGIXNG_DIGITAL_ACTIONS, LOGIXNG_DIGITAL_BOOLEAN_ACTIONS, LOGIXNG_DIGITAL_EXPRESSIONS, LOGIXNG_GLOBAL_VARIABLES, LOGIXNG_MODULES, LOGIXNG_STRING_ACTIONS, LOGIXNG_STRING_EXPRESSIONS, LOGIXNG_TABLES, LOGIXNGS, LOGIXS, MEMORIES, METERFRAMES, METERS, OBLOCKS, PANELFILES, REPORTERS, ROUTES, SECTIONS, SENSORGROUPS, SENSORS, SIGNALGROUPS, SIGNALHEADS, SIGNALMASTLOGICS, SIGNALMASTS, STRINGIOS, TIMEBASE, TRANSITS, TURNOUTS, WARRANTS
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description IdTag
getBySystemName(java.lang.String systemName)
Locate an instance based on a system name.IdTag
getByTagID(java.lang.String tagID)
Locate an instance based on a tag ID.IdTag
getByUserName(java.lang.String userName)
Locate an instance based on a user name.IdTag
getIdTag(java.lang.String name)
Locate via tag ID, then by user name, and finally system name if needed.java.util.List<IdTag>
getTagsForReporter(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.void
init()
Perform initialization.boolean
isFastClockUsed()
Determines if fast clock times should be recorded for when a given IdTag was last seen.boolean
isInitialised()
Determines if the manager has been initialized.boolean
isStateStored()
Determines if the state of known IdTags should be stored.IdTag
newIdTag(java.lang.String systemName, java.lang.String userName)
Return an instance with the specified system and user names.IdTag
provideIdTag(java.lang.String name)
Locate via tag ID, then user name, and finally system name if needed.void
setFastClockUsed(boolean fastClock)
Define if the manager should use the fast clock when setting the times when a given IdTag was last seen.void
setStateStored(boolean state)
Define if the manager should persist details of when and where all known IdTags were seen.-
Methods inherited from interface jmri.Manager
addDataListener, deleteBean, deregister, dispose, getBeanTypeHandled, getBeanTypeHandled, getEntryToolTip, getKnownBeanProperties, getMemo, getNamedBean, getNamedBeanClass, getNamedBeanSet, getObjectCount, getSubSystemNamePrefix, getSystemNamePrefix, getSystemPrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, makeSystemName, register, removeDataListener, setDataListenerMute, typeLetter, validateBadCharsInSystemNameFormat, validateIntegerSystemNameFormat, validateNmraAccessorySystemNameFormat, validateSystemNameFormat, validateSystemNameFormat, validateSystemNameFormatOnlyNumeric, validateSystemNamePrefix, validateTrimmedMin1NumberSystemNameFormat, validateTrimmedSystemNameFormat, validateUppercaseTrimmedSystemNameFormat, validSystemNameFormat
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
Methods inherited from interface jmri.ProvidingManager
provide
-
Methods inherited from interface jmri.beans.SilenceablePropertyChangeProvider
setPropertyChangesSilenced
-
Methods inherited from interface jmri.beans.VetoableChangeProvider
addVetoableChangeListener, addVetoableChangeListener, getVetoableChangeListeners, getVetoableChangeListeners, removeVetoableChangeListener, removeVetoableChangeListener
-
-
-
-
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
-
getBySystemName
@CheckReturnValue @CheckForNull IdTag getBySystemName(@Nonnull java.lang.String systemName)
Locate an instance based on a system name. Returns null if no instance already exists.- Specified by:
getBySystemName
in interfaceManager<IdTag>
- Parameters:
systemName
- system name being requested- Returns:
- requested IdTag object or null if none exists
-
getByUserName
@CheckReturnValue @CheckForNull IdTag getByUserName(@Nonnull java.lang.String userName)
Locate an instance based on a user name. Returns null if no instance already exists.- Specified by:
getByUserName
in interfaceManager<IdTag>
- Parameters:
userName
- user name being requested- Returns:
- requested IdTag object or null if none exists
-
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.
- Parameters:
systemName
- the system nameuserName
- 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 forthreshold
- 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.
-
isInitialised
@CheckReturnValue boolean isInitialised()
Determines if the manager has been initialized.- Returns:
- state of initialization
-
-