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}