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}