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}