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}