001package jmri;
002
003import java.util.List;
004import javax.annotation.CheckForNull;
005import javax.annotation.CheckReturnValue;
006import javax.annotation.Nonnull;
007
008/**
009 * Locate an IdTag object representing a specific IdTag.
010 * <p>
011 * IdTag objects are obtained from an IdTagManager, which in turn is generally
012 * located from the InstanceManager. A typical call sequence might be:
013 * <pre>
014 * IdTag tag = InstanceManager.idTagManagerInstance().newIdTag(null,"23");
015 * </pre>
016 * <p>
017 * Each IdTag has a two names. The "user" name is entirely free form, and can be
018 * used for any purpose. The "system" name is provided by the system-specific
019 * implementations, and provides a unique mapping to the layout control system
020 * (for example LocoNet or NCE) and address within that system.
021 * <p>
022 * Much of the book-keeping is implemented in the AbstractIdTagManager class,
023 * which can form the basis for a system-specific implementation.
024 *
025 * <hr>
026 * This file is part of JMRI.
027 * <p>
028 * JMRI is free software; you can redistribute it and/or modify it under the
029 * terms of version 2 of the GNU General Public License as published by the Free
030 * Software Foundation. See the "COPYING" file for a copy of this license.
031 * <p>
032 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
033 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
034 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
035 *
036 * @author Bob Jacobsen Copyright (C) 2001
037 * @author Matthew Harris Copyright (C) 2011
038 * @see jmri.IdTag
039 * @see jmri.InstanceManager
040 * @since 2.11.4
041 */
042public interface IdTagManager extends ProvidingManager<IdTag> {
043
044    /**
045     * Locate via tag ID, then user name, and finally system name if needed. If
046     * that fails, create a new IdTag. If the name is a valid system name, it
047     * will be used for the new IdTag. Otherwise, the makeSystemName method will
048     * attempt to turn it into a valid system name.
049     *
050     * @param name Tag ID, user name, system name, or address which can be
051     *             promoted to system name
052     * @return A tag ID
053     * @throws IllegalArgumentException if IdTag doesn't already exist and the
054     *                                  manager cannot create the IdTag due to
055     *                                  an illegal name or name that can't
056     *                                  be parsed.
057     */
058    @Nonnull
059    IdTag provideIdTag(@Nonnull String name) throws IllegalArgumentException;
060
061    /**
062     * Locate via tag ID, then by user name, and finally system name if needed.
063     * If that fails, return null
064     *
065     * @param name tag name being requested
066     * @return null if no match found
067     */
068    @CheckReturnValue
069    @CheckForNull
070    IdTag getIdTag(@Nonnull String name);
071
072    /**
073     * Locate an instance based on a system name. Returns null if no instance
074     * already exists.
075     *
076     * @param systemName system name being requested
077     * @return requested IdTag object or null if none exists
078     */
079    @Override
080    @CheckReturnValue
081    @CheckForNull
082    IdTag getBySystemName(@Nonnull String systemName);
083
084    /**
085     * Locate an instance based on a user name. Returns null if no instance
086     * already exists.
087     *
088     * @param userName user name being requested
089     * @return requested IdTag object or null if none exists
090     */
091    @Override
092    @CheckReturnValue
093    @CheckForNull
094    IdTag getByUserName(@Nonnull String userName);
095
096    /**
097     * Locate an instance based on a tag ID. Returns null if no instance already
098     * exists.
099     *
100     * @param tagID tag ID being requested
101     * @return requested IdTag object or null if none exists
102     */
103    @CheckReturnValue
104    @CheckForNull
105    IdTag getByTagID(@Nonnull String tagID);
106
107    /**
108     * Return an instance with the specified system and user names. Note that
109     * two calls with the same arguments will get the same instance; there is
110     * only one IdTag object representing a given physical IdTag and therefore
111     * only one with a specific system or user name.
112     * <p>
113     * This will always return a valid object reference; a new object will be
114     * created if necessary. In that case:
115     * <ul>
116     * <li>If a null reference is given for user name, no user name will be
117     * associated with the IdTag object created; a valid system name must be
118     * provided
119     * <li>If both are provided, the system name defines the hardware access of
120     * the desired IdTag, and the user address is associated with it. The system
121     * name must be valid.
122     * </ul>
123     * Note that it is possible to make an inconsistent request if both
124     * addresses are provided, but the given values are associated with
125     * different objects. This is a problem, and we don't have a good solution
126     * except to issue warnings. This will mostly happen if you're creating
127     * RfidTags when you should be looking them up.
128     *
129     * @param systemName the system name
130     * @param userName   the user name
131     * @return requested IdTag object (never null)
132     * @throws IllegalArgumentException if cannot create the IdTag due to e.g.
133     *                                  an illegal name or name that can't be
134     *                                  parsed.
135     */
136    @Nonnull
137    IdTag newIdTag(@Nonnull String systemName, @CheckForNull String userName) throws IllegalArgumentException;
138
139    /**
140     * Get a list of all IdTags seen by a specified Reporter within a specific
141     * time threshold from the most recently seen.
142     *
143     * @param reporter  Reporter to return list for
144     * @param threshold Time threshold (in ms)
145     * @return List of matching IdTags
146     */
147    @CheckReturnValue
148    @Nonnull
149    List<IdTag> getTagsForReporter(@Nonnull Reporter reporter, long threshold);
150
151    /**
152     * Define if the manager should persist details of when and where all known
153     * IdTags were seen.
154     *
155     * @param state True to store; False to omit
156     */
157    void setStateStored(boolean state);
158
159    /**
160     * Determines if the state of known IdTags should be stored.
161     *
162     * @return True to store state; False to discard state
163     */
164    @CheckReturnValue
165    boolean isStateStored();
166
167    /**
168     * Define if the manager should use the fast clock when setting the times
169     * when a given IdTag was last seen.
170     *
171     * @param fastClock True to use the fast clock; False to use the system
172     *                  clock
173     */
174    void setFastClockUsed(boolean fastClock);
175
176    /**
177     * Determines if fast clock times should be recorded for when a given IdTag
178     * was last seen.
179     *
180     * @return True to use the fast clock; False to use the system clock
181     */
182    @CheckReturnValue
183    boolean isFastClockUsed();
184
185    /**
186     * Perform initialization.
187     */
188    void init();
189
190    /**
191     * Determines if the manager has been initialized.
192     *
193     * @return state of initialization
194     */
195    @CheckReturnValue
196    boolean isInitialised();
197
198}