001package jmri;
002
003import javax.annotation.CheckReturnValue;
004import javax.annotation.Nonnull;
005
006import jmri.beans.PropertyChangeProvider;
007
008/**
009 * Provide controls for layout power.
010 * <p>
011 * The PowerManager handles three states:
012 * <ul>
013 * <li>On/Off which controls electrical power to the track
014 * <li>an optional "Idle" state, where track power is alive but track-connected
015 *     decoders may be un-controllable
016 * </ul>
017 * A layout may not have control over these, in which case attempts to change
018 * them should return an exception. If the state cannot be sensed, that should
019 * also return an exception.
020 * <p>
021 * Some connections, including some LocoNet-based connections, implement the "Idle"
022 * state.  For these LocoNet-based connections, when the Power state is "Idle", the
023 * track power is alive and the command station is broadcasting "stop" to all mobile
024 * decoders. Other systems may implement different interpretation of the "Idle" state.
025 *
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 */
039public interface PowerManager extends PropertyChangeProvider {
040
041    int UNKNOWN = NamedBean.UNKNOWN;
042    int ON = 0x02;
043    int OFF = 0x04;
044    int IDLE = 0x08; // not supported by some connection types
045
046    /**
047     * {@link java.beans.PropertyChangeEvent}s are fired with this property name.
048     * <p>
049     * {@value #POWER}
050     */
051    String POWER = "power"; // as recommended in JavaBeans Spec // NOI18N
052
053    void setPower(int v) throws JmriException;
054
055    @CheckReturnValue
056    int getPower();
057
058    // to free resources when no longer used
059    void dispose() throws JmriException;
060
061    default boolean implementsIdle() {
062        // By default the Power Manager does not implement the IDLE power state
063        return false;
064    }
065
066    @CheckReturnValue
067    @Nonnull String getUserName();
068}