001package jmri; 002 003import java.util.Date; 004import javax.annotation.CheckForNull; 005import javax.annotation.Nonnull; 006import org.jdom2.Element; 007 008/** 009 * IdTag is a pre-parsed representation of an identification message from the 010 * layout. One use of an IdTag is a device that might be attached to any 011 * specific piece of rolling stock to uniquely identify it. 012 * <p> 013 * Examples include 014 * <ul> 015 * <li>RFID-tag.</li> 016 * <li>Digitrax Transponding Decoders</li> 017 * <li>RailCom tags</li> 018 * </ul> 019 * <p> 020 * Each IdTag contains the following information: 021 * <ul> 022 * <li>A System Name</li> 023 * <li>A User Name (which may be null)</li> 024 * <li>A TagID<li> 025 * <li>A reference to the last reporter to see the tag, which may be null</li> 026 * <li>The date and time the last reporter saw the tag, which may be null</li> 027 * <li>A list of key/value pairs holding properties</li> 028 * </ul> 029 * <p> 030 * "Seen" is defined as a Reporter has indicated that the IdTag is within the 031 * area served by that Reporter. "Seen" is not updated to a Reporter reports that the IdTag is 032 * leaving that area. 033 * <p> 034 * The system name is of the form "sDxxxx" where "xxxx" is the same value as the TagID 035 * and "s" is the system prefix for the relevant Reporter (for Reporter-type-specific tags) 036 * or "I" in the more general case. 037 * <p> 038 * The list of key value pairs is maintained by the reporters parsing and 039 * updating the list. This information may vary between implementations. 040 * <hr> 041 * This file is part of JMRI. 042 * <p> 043 * JMRI is free software; you can redistribute it and/or modify it under the 044 * terms of version 2 of the GNU General Public License as published by the Free 045 * Software Foundation. See the "COPYING" file for a copy of this license. 046 * <p> 047 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 048 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 049 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 050 * 051 * @author Matthew Harris Copyright (C) 2011 052 * @since 2.11.4 053 */ 054public interface IdTag extends NamedBean { 055 056 /** 057 * Constant representing an "unseen" state, indicating that the ID tag has 058 * not yet been seen. 059 */ 060 static final int UNSEEN = 0x02; 061 062 /** 063 * Constant representing a "seen" state, indicating that the tag has been 064 * seen. 065 * <p> 066 * To determine where this object was last seen, use: 067 * <ul> 068 * <li>{@link #getWhereLastSeen()} 069 * </ul> 070 * To determine when this object was last seen, use: 071 * <ul> 072 * <li>{@link #getWhenLastSeen()} 073 * </ul> 074 */ 075 static final int SEEN = 0x03; 076 077 /** 078 * Retrieve a string representation of this tag ID 079 * <p> 080 * This is the system name without the identifier 081 * 082 * @return the tag ID 083 */ 084 @Nonnull 085 String getTagID(); 086 087 /** 088 * Set the Reporter that last saw this tag. 089 * <p> 090 * Also sets the Date/Time when last seen 091 * 092 * @param reporter Reporter object where last seen 093 * @see #getWhereLastSeen() 094 * @see #getWhenLastSeen() 095 */ 096 void setWhereLastSeen(Reporter reporter); 097 098 /** 099 * Return the Reporter that last saw this tag, or null if not yet seen 100 * 101 * @return Reporter object where last seen, or null 102 */ 103 @CheckForNull 104 Reporter getWhereLastSeen(); 105 106 /** 107 * Return the Date/Time when this tag was last seen, or null if not yet seen 108 * 109 * @return Date object when last seen, or null 110 */ 111 @CheckForNull 112 Date getWhenLastSeen(); 113 114 /** 115 * Store the contents of this IdTag object as an XML element 116 * 117 * @param storeState Determine if the state of this IdTag should be stored 118 * @return Element with IdTag contents 119 */ 120 Element store(boolean storeState); 121 122 /** 123 * Load contents of IdTag object from an XML element 124 * 125 * @param e Element containing IdTag details 126 */ 127 void load(@Nonnull Element e); 128 129}