001package jmri;
002
003/**
004 * Represent a device that can report identification information.
005 * <p>
006 * Reporting devices might include:
007 * <ul>
008 * <li>A DCC device that reports a locomotive number when it's in a particular
009 * location
010 * <li>A device that reports something about the layout environment, e.g. the
011 * current drawn or light intensity
012 * <li>A device that reacts to some happening on the layout with a complicated
013 * report
014 * </ul>
015 * <p>
016 * In contrast to Sensors, a Reporter provides more detailed information. A
017 * Sensor provides a status of ACTIVE or INACTIVE, while a Reporter returns an
018 * Object. The real type of that object can be whatever a particular Reporter
019 * finds useful to report. Typical values might be a String, Int, or 
020 * {@link IdTag}, 
021 * all of which can be displayed, printed, equated, etc.
022 * <p>
023 * A Reporter might also not be able to report all the time. The previous value
024 * remains available, but it's also possible to distinguish this case by using
025 * the getCurrentReport member function.
026 * <hr>
027 * <p>The various implementations of the Reporter interface:
028 * <a href="doc-files/Reporter.png"><img src="doc-files/Reporter.png" alt="Class diagram of Reporter implementations" height="50%" width="50%"></a>
029 * <br>
030 * <hr>
031 * This file is part of JMRI.
032 * <p>
033 * JMRI is free software; you can redistribute it and/or modify it under the
034 * terms of version 2 of the GNU General Public License as published by the Free
035 * Software Foundation. See the "COPYING" file for a copy of this license.
036 * <p>
037 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
038 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
039 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
040 *
041 * @author Bob Jacobsen Copyright (C) 2001, 2023
042 * @author Matthew Harris Copyright (C) 2011
043 * @see jmri.Sensor
044 * @see jmri.ReporterManager
045 * @see jmri.InstanceManager
046 */
047 
048/*
049@startuml jmri/doc-files/Reporter.png
050
051note as N1 #E0E0FF
052    Caution:  This class diagram is
053    manually maintained, and may be 
054    incomplete. The CollectingReporter
055    interface is omitted for simplicity.
056end note
057
058interface Reporter
059
060abstract AbstractReporter
061Reporter <|-- AbstractReporter
062
063abstract AbstractIdTagReporter
064AbstractReporter <|-- AbstractIdTagReporter
065PhysicalLocationReporter <|-- AbstractIdTagReporter
066
067class EcosReporter
068AbstractReporter <|-- EcosReporter
069class JMRIClientReporter
070AbstractReporter <|-- JMRIClientReporter
071
072class RpsReporter
073AbstractReporter <|-- RpsReporter
074class TrackReporter
075AbstractReporter <|-- TrackReporter
076
077interface PhysicalLocationReporter
078
079class LnReporter
080AbstractIdTagReporter <|-- LnReporter
081class MqttReporter
082AbstractIdTagReporter <|-- MqttReporter
083class OlcbReporter
084AbstractIdTagReporter <|-- OlcbReporter
085class RfidReporter
086AbstractIdTagReporter <|-- RfidReporter
087
088abstract AbstractRailComReporter
089AbstractIdTagReporter <|-- AbstractRailComReporter
090
091class CbusReporter
092AbstractRailComReporter <|-- CbusReporter
093class Dcc4PcReporter
094AbstractRailComReporter <|-- Dcc4PcReporter
095class Z21CanReporter
096AbstractRailComReporter <|-- Z21CanReporter
097class Z21Reporter
098AbstractRailComReporter <|-- Z21Reporter
099
100@enduml
101*/
102
103public interface Reporter extends NamedBean {
104
105    /**
106     * String constant for last Report.
107     */
108    String PROPERTY_LAST_REPORT = "lastReport";
109
110    /**
111     * String constant for current Report.
112     */
113    String PROPERTY_CURRENT_REPORT = "currentReport";
114
115    /**
116     * String constant for report metadata updates.
117     */
118    String PROPERTY_REPORT_METADATA = "reportMetadata";
119
120    /**
121     * String constant for collection updates on collecting reporters.
122     */
123    String PROPERTY_COLLECTION = "collection";
124
125    /**
126     * Query the last report. This will return a value even if there's no
127     * current report available. If there is a current report, both this and the
128     * current report will be equal. If nothing has ever been reported, this
129     * will return a null object.
130     *
131     * @return the last report or null
132     */
133    Object getLastReport();
134
135    /**
136     * Query the current report. If there is no current report available (e.g.
137     * the reporting hardware says no information is currently available) this
138     * will return a null object.
139     *
140     * @return the current report or null
141     */
142    Object getCurrentReport();
143
144    /**
145     * Set the report to an arbitrary object.
146     * <p>
147     * A Reporter object will usually just "report"; its contents usually come
148     * from the layout, and hence are only set by lower-level implementation
149     * classes. But there are occasionally reasons to set it from inside the
150     * program, e.g. debugging via entering values in the Reporter Table. Hence
151     * provision of this method.
152     *
153     * @param r the report
154     */
155    void setReport(Object r);
156
157    /**
158     * Provide an integer form of the last report.
159     *
160     */
161    @Override
162    int getState();
163
164    /**
165     * Informs this reporter that a tag previously reported here has been
166     * seen at another reporter.
167     *
168     * @param tag the tag seen elsewhere
169     * @param newReporter the reporter where the tag was newly detected
170     */
171    void notifySeenElsewhere(IdTag tag, Reporter newReporter);
172
173}