jmri
Interface IdTagManager

Show UML class diagram

All Superinterfaces:

Manager

All Known Subinterfaces:

RailComManager

All Known Implementing Classes:

DefaultIdTagManager, DefaultRailComManager

public interface IdTagManager
extends Manager

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 (e.g. LocoNet, NCE, etc) 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

Field Summary

Fields inherited from interface jmri.Manager

AUDIO, BLOCKBOSS, BLOCKS, CONDITIONALS, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXS, MEMORIES, OBLOCKS, PANELFILES, REPORTERS, ROUTES, SECTIONS, SENSORGROUPS, SENSORS, SIGNALGROUPS, SIGNALHEADS, SIGNALMASTLOGICS, SIGNALMASTS, TIMEBASE, TRANSITS, TURNOUTS, WARRANTS

Method Summary

IdTag	getBySystemName(String systemName) Locate an instance based on a system name.
IdTag	getByTagID(String tagID) Locate an instance based on a tag ID.
IdTag	getByUserName(String userName) Locate an instance based on a user name.
IdTag	getIdTag(String name) Locate via tag ID, then by user name, and finally system name if needed.
List<String>	getSystemNameList() Get a list of all IdTag's system names.
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 initialisation
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 initialised
boolean	isStateStored() Determines if the state of known IdTags should be stored
IdTag	newIdTag(String systemName, String userName) Return an instance with the specified system and user names.
IdTag	provideIdTag(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

addPropertyChangeListener, deregister, dispose, getBeanBySystemName, getBeanByUserName, getNamedBean, getNamedBeanList, getSystemNameArray, getSystemPrefix, getXMLOrder, makeSystemName, register, removePropertyChangeListener, systemLetter, typeLetter

Method Detail

provideIdTag

IdTag provideIdTag(String name)

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:

Never null

Throws:

IllegalArgumentException - if IdTag doesn't already exist and the manager cannot create the IdTag due to e.g. an illegal name or name that can't be parsed.

getIdTag

IdTag getIdTag(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

IdTag getBySystemName(String systemName)

Locate an instance based on a system name. Returns null if no instance already exists.

Parameters:

systemName - system name being requested

Returns:

requested IdTag object or null if none exists

getByUserName

IdTag getByUserName(String userName)

Locate an instance based on a user name. Returns null if no instance already exists.

Parameters:

userName - user name being requested

Returns:

requested IdTag object or null if none exists

getByTagID

IdTag getByTagID(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

IdTag newIdTag(String systemName,
               String userName)

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.

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.

getSystemNameList

List<String> getSystemNameList()

Get a list of all IdTag's system names.

Specified by:

getSystemNameList in interface Manager

getTagsForReporter

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.

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

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

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 initialisation

isInitialised

boolean isInitialised()

Determines if the manager has been initialised

Returns:

state of initialisation