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}