001package jmri; 002 003import java.util.List; 004import javax.annotation.CheckForNull; 005import javax.annotation.Nonnull; 006import jmri.beans.PropertyChangeProvider; 007 008/** 009 * Get access to available {@link Programmer} objects. 010 * <p> 011 * Programmers come in two types: 012 * <ul> 013 * <li>Global, previously "Service Mode" or on a programming track. Request 014 * these from an instance of {@link GlobalProgrammerManager}. 015 * <li>Addressed, previously "Ops Mode" also known as "programming on the main". 016 * Request these from an instance of this interface. 017 * </ul> 018 * You get a {@link Programmer} object from a ProgrammerManager, which in turn 019 * can be located from the {@link InstanceManager}. 020 * <p> 021 * This interface also provides a reserve/release system for tools that want to 022 * pretend they have exclusive use of a Programmer. This is a cooperative 023 * reservation; both tools (first and second reserver) must be using the 024 * reserve/release interface. 025 * <p> 026 * This file is part of JMRI. 027 * <p> 028 * JMRI is free software; you can redistribute it and/or modify it under the 029 * terms of version 2 of the GNU General Public License as published by the Free 030 * Software Foundation. See the "COPYING" file for a copy of this license. 031 * <p> 032 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 033 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 034 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 035 * 036 * @see jmri.Programmer 037 * @author Bob Jacobsen Copyright (C) 2001, 2008, 2014 038 * @since 3.9.6 039 */ 040public interface AddressedProgrammerManager extends PropertyChangeProvider { 041 042 /** 043 * Gain access to a Addressed Mode Programmer without reservation. 044 * 045 * @param pLongAddress true if this is a long (14 bit) address, else false 046 * @param pAddress specific decoder address to use 047 * @return null only if there isn't an Ops Mode Programmer in the system 048 */ 049 @CheckForNull 050 AddressedProgrammer getAddressedProgrammer(boolean pLongAddress, int pAddress); 051 052 /** 053 * Gain access to a Addressed Mode Programmer without reservation. 054 * 055 * @param address specific decoder address to use 056 * @return null only if there isn't an Ops Mode Programmer in the system 057 */ 058 @CheckForNull 059 default AddressedProgrammer getAddressedProgrammer(@Nonnull DccLocoAddress address) { 060 return this.getAddressedProgrammer(address.isLongAddress(), address.getNumber()); 061 } 062 063 /** 064 * Gain access to a (the) Addressed Mode Programmer, in the process 065 * reserving it for yourself. 066 * 067 * @param pLongAddress true if this is a long (14 bit) address, else false 068 * @param pAddress Specific decoder address to use 069 * @return null if the address is in use by a reserved programmer 070 */ 071 @CheckForNull 072 AddressedProgrammer reserveAddressedProgrammer(boolean pLongAddress, int pAddress); 073 074 /** 075 * Gain access to a (the) Addressed Mode Programmer, in the process 076 * reserving it for yourself. 077 * 078 * @param address specific decoder address to use 079 * @return null if the address is in use by a reserved programmer 080 */ 081 @CheckForNull 082 default AddressedProgrammer reserveAddressedProgrammer(@Nonnull DccLocoAddress address) { 083 return this.reserveAddressedProgrammer(address.isLongAddress(), address.getNumber()); 084 } 085 086 /** 087 * Return access to an Addressed Mode Programmer, so that it can be used 088 * elsewhere. 089 * 090 * @param p the programmer to release 091 */ 092 void releaseAddressedProgrammer(@Nonnull AddressedProgrammer p); 093 094 /** 095 * Convenience method to check whether you'll be able to get an Addressed 096 * Mode programmer. 097 * 098 * @return false if there's no chance of getting one 099 */ 100 boolean isAddressedModePossible(); 101 102 /** 103 * Convenience method to check whether you'll be able to get an Addressed 104 * Mode programmer for a specific address 105 * 106 * @param address the address to get a programmer for 107 * @return false if there's no chance of getting one 108 */ 109 boolean isAddressedModePossible(@Nonnull LocoAddress address); 110 111 /** 112 * Get the list of {@link ProgrammingMode} (generally) supported by 113 * Programmers provided by this Manager. 114 * <p> 115 * Use this to enquire about modes before you're ready to request a specific 116 * programmer. 117 * <p> 118 * If the order is significant, earlier modes are better. 119 * 120 * @return the programming modes or an empty list 121 */ 122 @Nonnull 123 List<ProgrammingMode> getDefaultModes(); 124 125 /** 126 * Provides the human-readable representation for including 127 * ProgrammerManagers directly in user interface controls, so it should 128 * return a user-provided name for this particular one. 129 * 130 * @return the name for the programmer 131 */ 132 @Nonnull 133 String getUserName(); 134 135 /** 136 * Provides the human-readable representation for including 137 * ProgrammerManagers directly in user interface controls, so it should 138 * return a user-provided name for this particular one. 139 * 140 * @return the name for the programmer 141 */ 142 @Nonnull 143 @Override 144 String toString(); 145}