001package jmri; 002 003import java.util.SortedSet; 004import javax.annotation.CheckForNull; 005import javax.annotation.Nonnull; 006import jmri.jmrit.audio.AudioFactory; 007 008/** 009 * Locate an Audio object representing some specific audio information. 010 * <p> 011 * Audio objects are obtained from an AudioManager, which in turn is generally 012 * located from the InstanceManager. A typical call sequence might be: 013 * <pre> 014 * Audio audio = InstanceManager.getDefault(jmri.AudioManager.class).provideAudio("myAudio"); 015 * </pre> 016 * <p> 017 * Each Audio has two names. The "user" name is entirely free form, and can be 018 * used for any purpose. The "system" name is provided by the system-specific 019 * implementations, if any, and provides a unique mapping to the layout control 020 * system (for example LocoNet or NCE) and address within that system. Note that 021 * most (all?) layout systems don't have anything corresponding to this, in 022 * which case the "Internal" Audio objects are still available with names like 023 * IAS23. 024 * <p> 025 * Much of the book-keeping is implemented in the AbstractAudioManager class, 026 * which can form the basis for a system-specific implementation. 027 * <hr> 028 * This file is part of JMRI. 029 * <p> 030 * JMRI is free software; you can redistribute it and/or modify it under the 031 * terms of version 2 of the GNU General Public License as published by the Free 032 * Software Foundation. See the "COPYING" file for a copy of this license. 033 * <p> 034 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 035 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 036 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 037 * 038 * @author Matthew Harris Copyright (c) 2009 039 */ 040public interface AudioManager extends Manager<Audio> { 041 042 /** 043 * Define the maximum number of AudioListener objects that can be created 044 */ 045 int MAX_LISTENERS = 1; 046 047 /** 048 * Define the maximum number of AudioSource objects that can be created 049 */ 050 int MAX_SOURCES = 255; 051 052 /** 053 * Define the maximum number of AudioBuffer objects that can be created 054 */ 055 int MAX_BUFFERS = 255; 056 057 /** 058 * Get the Audio with the user name, then system name if needed; if that fails, create a 059 * new Audio. 060 * If the name is a valid system name, it will be used for the 061 * new Audio. Otherwise, the makeSystemName method will attempt to turn it 062 * into a valid system name. 063 * 064 * @param name User name or system name to match, or which can be promoted 065 * to system name 066 * @return Never null under normal circumstances 067 * @throws AudioException if error occurs during creation 068 */ 069 @Nonnull 070 Audio provideAudio(@Nonnull String name) throws AudioException; 071 072 /** 073 * Get an existing Audio or return null if it doesn't exists. 074 * 075 * Locates via user name, then system name if needed. 076 * 077 * @param name User name or system name to match 078 * @return null if no match found 079 */ 080 @CheckForNull 081 Audio getAudio(@Nonnull String name); 082 083 /** 084 * Get the Audio with the given system name or return null if no instance 085 * already exists. 086 * 087 * @param systemName Audio object system name (such as IAS1 or IAB4) 088 * @return requested Audio object or null if none exists 089 */ 090 @Override 091 @CheckForNull 092 Audio getBySystemName(@Nonnull String systemName); 093 094 /** 095 * Get the Audio with the given user name or return null if no instance 096 * already exists. 097 * 098 * @param userName Audio object user name 099 * @return requested Audio object or null if none exists 100 */ 101 @Override 102 @CheckForNull 103 Audio getByUserName(@Nonnull String userName); 104 105 /** 106 * Return an Audio with the specified system and user names. 107 * Note that 108 * two calls with the same arguments will get the same instance; there is 109 * only one Audio object representing a given physical Audio and therefore 110 * only one with a specific system or user name. 111 * <p> 112 * This will always return a valid object reference; a new object will be 113 * created if necessary. In that case: 114 * <ul> 115 * <li>If a null reference is given for user name, no user name will be 116 * associated with the Audio object created; a valid system name must be 117 * provided 118 * <li>If both names are provided, the system name defines the hardware 119 * access of the desired Audio, and the user address is associated with it. 120 * The system name must be valid. 121 * </ul> 122 * Note that it is possible to make an inconsistent request if both 123 * addresses are provided, but the given values are associated with 124 * different objects. This is a problem, and we don't have a good solution 125 * except to issue warnings. This will mostly happen if you're creating 126 * Audio objects when you should be looking them up. 127 * 128 * @param systemName Audio object system name (such as IAS1 or IAB4) 129 * @param userName Audio object user name 130 * @return requested Audio object (never null) 131 * @throws AudioException if error occurs during creation 132 */ 133 @Nonnull 134 Audio newAudio(@Nonnull String systemName, String userName) throws AudioException; 135 136 /** 137 * Returns the currently active AudioFactory object. 138 * <p> 139 * An Audio factory is responsible for the creation of implementation 140 * specific audio objects. 141 * 142 * @return current active AudioFactory object 143 */ 144 @CheckForNull 145 AudioFactory getActiveAudioFactory(); 146 147 /** 148 * Get the specified Audio sub-type NamedBeans. 149 * 150 * @param subType sub-type to retrieve 151 * @return Unmodifiable access to a SortedSet of NamedBeans for the specified Audio sub-type . 152 * 153 * @since 4.17.6 154 */ 155 @Nonnull 156 SortedSet<Audio> getNamedBeanSet(char subType); 157 158 /** 159 * Perform any initialisation operations 160 */ 161 void init(); 162 163 /** 164 * Perform any clean-up operations 165 */ 166 void cleanup(); 167 168 /** 169 * Determine if this AudioManager is initialised 170 * @return true if initialised 171 */ 172 boolean isInitialised(); 173 174}