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 or Int, both of 020 * which can be displayed, printed, equated, etc. 021 * <p> 022 * A Reporter might also not be able to report all the time. The previous value 023 * remains available, but it's also possible to distinguish this case by using 024 * the getCurrentReport member function. 025 * <br> 026 * <hr> 027 * This file is part of JMRI. 028 * <p> 029 * JMRI is free software; you can redistribute it and/or modify it under the 030 * terms of version 2 of the GNU General Public License as published by the Free 031 * Software Foundation. See the "COPYING" file for a copy of this license. 032 * <p> 033 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 034 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 035 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 036 * 037 * @author Bob Jacobsen Copyright (C) 2001 038 * @author Matthew Harris Copyright (C) 2011 039 * @see jmri.Sensor 040 * @see jmri.ReporterManager 041 * @see jmri.InstanceManager 042 */ 043public interface Reporter extends NamedBean { 044 045 /** 046 * Query the last report. This will return a value even if there's no 047 * current report available. If there is a current report, both this and the 048 * current report will be equal. If nothing has ever been reported, this 049 * will return a null object. 050 * 051 * @return the last report or null 052 */ 053 public Object getLastReport(); 054 055 /** 056 * Query the current report. If there is no current report available (e.g. 057 * the reporting hardware says no information is currently available) this 058 * will return a null object. 059 * 060 * @return the current report or null 061 */ 062 public Object getCurrentReport(); 063 064 /** 065 * Set the report to an arbitrary object. 066 * <p> 067 * A Reporter object will usually just "report"; its contents usually come 068 * from the layout, and hence are only set by lower-level implementation 069 * classes. But there are occasionally reasons to set it from inside the 070 * program, e.g. debugging via entering values in the Reporter Table. Hence 071 * provision of this method. 072 * 073 * @param r the report 074 */ 075 public void setReport(Object r); 076 077 /** 078 * Provide an integer form of the last report. 079 * 080 */ 081 @Override 082 public int getState(); 083 084}