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}