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     * Query the last report. This will return a value even if there's no
107     * current report available. If there is a current report, both this and the
108     * current report will be equal. If nothing has ever been reported, this
109     * will return a null object.
110     *
111     * @return the last report or null
112     */
113    Object getLastReport();
114
115    /**
116     * Query the current report. If there is no current report available (e.g.
117     * the reporting hardware says no information is currently available) this
118     * will return a null object.
119     *
120     * @return the current report or null
121     */
122    Object getCurrentReport();
123
124    /**
125     * Set the report to an arbitrary object.
126     * <p>
127     * A Reporter object will usually just "report"; its contents usually come
128     * from the layout, and hence are only set by lower-level implementation
129     * classes. But there are occasionally reasons to set it from inside the
130     * program, e.g. debugging via entering values in the Reporter Table. Hence
131     * provision of this method.
132     *
133     * @param r the report
134     */
135    void setReport(Object r);
136
137    /**
138     * Provide an integer form of the last report.
139     *
140     */
141    @Override
142    int getState();
143
144}