001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.Nonnull;
005import jmri.beans.PropertyChangeProvider;
006
007/**
008 * Get access to available {@link Programmer} objects.
009 * <p>
010 * Programmers come in two types:
011 * <ul>
012 * <li>Global, previously "Service Mode" or on a programming track. Request
013 * these from an instance of this interface.
014 * <li>Addressed, previously "Ops Mode" also known as "programming on the main". Request
015 * these from an instance of {@link AddressedProgrammerManager}.
016 * </ul>
017 * <p>
018 * This interface also provides a reserve/release system for tools that want to
019 * pretend they have exclusive use of a Programmer. This is a cooperative
020 * reservation; both tools (first and second reserver) must be using the
021 * reserve/release interface.
022 * <p>
023 * This file is part of JMRI.
024 * <p>
025 * JMRI is free software; you can redistribute it and/or modify it under the
026 * terms of version 2 of the GNU General Public License as published by the Free
027 * Software Foundation. See the "COPYING" file for a copy of this license.
028 * <p>
029 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
030 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
031 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
032 *
033 * @see jmri.Programmer
034 * @author Bob Jacobsen Copyright (C) 2001, 2008, 2014
035 * @since 3.9.6
036 */
037public interface GlobalProgrammerManager extends PropertyChangeProvider {
038
039    /**
040     * Gain access to the Global Mode Programmer without reservation.
041     *
042     * @return null only if there isn't a Global Mode Programmer available via
043     *         this Manager.
044     */
045    @CheckForNull
046    Programmer getGlobalProgrammer();
047
048    /**
049     * Gain access to the Global Mode Programmer, in the process reserving it
050     * for yourself.
051     *
052     * @return null if the existing Global Mode programmer is in use
053     */
054    @CheckForNull
055    Programmer reserveGlobalProgrammer();
056
057    /**
058     * Return access to the Global Mode Programmer, so that it can be used
059     * elsewhere.
060     *
061     * @param p the Programmer to release
062     */
063    void releaseGlobalProgrammer(@Nonnull Programmer p);
064
065    /**
066     * Convenience method to check whether you'll be able to get a Global Mode
067     * programmer.
068     *
069     * @return false if there's no chance of getting one
070     */
071    boolean isGlobalProgrammerAvailable();
072
073    /**
074     * Provides the human-readable representation for including
075     * ProgrammerManagers directly in user interface components, so it should return a
076     * user-provided name for this particular one.
077     *
078     * @return user name of the GlobalProgrammerManager
079     */
080    @Nonnull
081    String getUserName();
082
083    /**
084     * toString() provides the human-readable representation for including
085     * ProgrammerManagers directly in user interface components, so it should return a
086     * user-provided name for this particular one.
087     *
088     * @return String representation of the GlobalProgrammerManager
089     */
090    @Nonnull
091    @Override
092    String toString();
093}