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    /**
054     * Set the Power.
055     * @param v the new power status.
056     * @throws jmri.JmriException if unable to send request.
057     */
058    void setPower(int v) throws JmriException;
059
060    /**
061     * Get the current power state.
062     * @return int value of state.
063     */
064    @CheckReturnValue
065    int getPower();
066
067    /**
068     * Free resources when no longer used.
069     * @throws jmri.JmriException if unable to dispose.
070     */
071    void dispose() throws JmriException;
072
073    /**
074     * Check if the connection supports the Idle power state.
075     * By default the Power Manager does not implement the IDLE power state.
076     * @return true if the connection implements Idle, else false.
077     */
078    default boolean implementsIdle() {
079        return false;
080    }
081
082    /**
083     * Request Track Power Status Update.
084     * Default implementation does nothing.
085     */
086    default void requestUpdateFromLayout() {}
087
088    /**
089     * Get the PowerManager UserName.
090     * @return a nonNull userName.
091     */
092    @CheckReturnValue
093    @Nonnull String getUserName();
094}