src/share/classes/javax/sound/midi/Synthesizer.java

Print this page


   1 /*
   2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.midi;
  27 
  28 import javax.sound.sampled.Control;
  29 
  30 
  31 /**
  32  * A <code>Synthesizer</code> generates sound.  This usually happens when one of
  33  * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a
  34  * {@link MidiChannel#noteOn(int, int) noteOn} message, either
  35  * directly or via the <code>Synthesizer</code> object.
  36  * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which
  37  * MIDI events can be delivered to the <code>Synthesizer</code>.
  38  * In such cases, the <code>Synthesizer</code> typically responds by sending
  39  * a corresponding message to the appropriate <code>MidiChannel</code>, or by
  40  * processing the event itself if the event isn't one of the MIDI channel
  41  * messages.
  42  * <p>
  43  * The <code>Synthesizer</code> interface includes methods for loading and
  44  * unloading instruments from soundbanks.  An instrument is a specification for synthesizing a
  45  * certain type of sound, whether that sound emulates a traditional instrument or is
  46  * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized
  47  * by bank and program number (via the instrument's <code>Patch</code> object).
  48  * Different <code>Synthesizer</code> classes might implement different sound-synthesis
  49  * techniques, meaning that some instruments and not others might be compatible with a
  50  * given synthesizer.
  51  * Also, synthesizers may have a limited amount of memory for instruments, meaning
  52  * that not every soundbank and instrument can be used by every synthesizer, even if
  53  * the synthesis technique is compatible.
  54  * To see whether the instruments from
  55  * a certain soundbank can be played by a given synthesizer, invoke the
  56  * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of
  57  * <code>Synthesizer</code>.
  58  * <p>
  59  * "Loading" an instrument means that that instrument becomes available for
  60  * synthesizing notes.  The instrument is loaded into the bank and
  61  * program location specified by its <code>Patch</code> object.  Loading does
  62  * not necessarily mean that subsequently played notes will immediately have
  63  * the sound of this newly loaded instrument.  For the instrument to play notes,
  64  * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received)
  65  * a program-change message that causes that particular instrument's
  66  * bank and program number to be selected.
  67  *

  68  * @see MidiSystem#getSynthesizer
  69  * @see Soundbank
  70  * @see Instrument
  71  * @see MidiChannel#programChange(int, int)
  72  * @see Receiver
  73  * @see Transmitter
  74  * @see MidiDevice
  75  *
  76  * @author Kara Kytle
  77  */
  78 public interface Synthesizer extends MidiDevice {
  79 
  80 
  81     // SYNTHESIZER METHODS
  82 
  83 
  84     /**
  85      * Obtains the maximum number of notes that this synthesizer can sound simultaneously.


  86      * @return the maximum number of simultaneous notes
  87      * @see #getVoiceStatus
  88      */
  89     public int getMaxPolyphony();
  90 
  91 
  92     /**
  93      * Obtains the processing latency incurred by this synthesizer, expressed in
  94      * microseconds.  This latency measures the worst-case delay between the
  95      * time a MIDI message is delivered to the synthesizer and the time that the
  96      * synthesizer actually produces the corresponding result.
  97      * <p>
  98      * Although the latency is expressed in microseconds, a synthesizer's actual measured
  99      * delay may vary over a wider range than this resolution suggests.  For example,
 100      * a synthesizer might have a worst-case delay of a few milliseconds or more.

 101      *
 102      * @return the worst-case delay, in microseconds
 103      */
 104     public long getLatency();
 105 
 106 
 107     /**
 108      * Obtains the set of MIDI channels controlled by this synthesizer.  Each
 109      * non-null element in the returned array is a <code>MidiChannel</code> that
 110      * receives the MIDI messages sent on that channel number.
 111      * <p>
 112      * The MIDI 1.0 specification provides for 16 channels, so this
 113      * method returns an array of at least 16 elements.  However, if this synthesizer
 114      * doesn't make use of all 16 channels, some of the elements of the array
 115      * might be <code>null</code>, so you should check each element
 116      * before using it.
 117      * @return an array of the <code>MidiChannel</code> objects managed by this
 118      * <code>Synthesizer</code>.  Some of the array elements may be <code>null</code>.

 119      */
 120     public MidiChannel[] getChannels();
 121 
 122 
 123     /**
 124      * Obtains the current status of the voices produced by this synthesizer.
 125      * If this class of <code>Synthesizer</code> does not provide voice
 126      * information, the returned array will always be of length 0.  Otherwise,
 127      * its length is always equal to the total number of voices, as returned by
 128      * <code>getMaxPolyphony()</code>.  (See the <code>VoiceStatus</code> class
 129      * description for an explanation of synthesizer voices.)
 130      *
 131      * @return an array of <code>VoiceStatus</code> objects that supply
 132      * information about the corresponding synthesizer voices
 133      * @see #getMaxPolyphony
 134      * @see VoiceStatus
 135      */
 136     public VoiceStatus[] getVoiceStatus();
 137 
 138 
 139     /**
 140      * Informs the caller whether this synthesizer is capable of loading
 141      * instruments from the specified soundbank.
 142      * If the soundbank is unsupported, any attempts to load instruments from
 143      * it will result in an <code>IllegalArgumentException</code>.

 144      * @param soundbank soundbank for which support is queried
 145      * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code>

 146      * @see #loadInstruments
 147      * @see #loadAllInstruments
 148      * @see #unloadInstruments
 149      * @see #unloadAllInstruments
 150      * @see #getDefaultSoundbank
 151      */
 152     public boolean isSoundbankSupported(Soundbank soundbank);
 153 
 154 
 155     /**
 156      * Makes a particular instrument available for synthesis.  This instrument
 157      * is loaded into the patch location specified by its <code>Patch</code>
 158      * object, so that if a program-change message is
 159      * received (or has been received) that causes that patch to be selected,
 160      * subsequent notes will be played using the sound of
 161      * <code>instrument</code>.  If the specified instrument is already loaded,
 162      * this method does nothing and returns <code>true</code>.
 163      * <p>
 164      * The instrument must be part of a soundbank
 165      * that this <code>Synthesizer</code> supports.  (To make sure, you can use
 166      * the <code>getSoundbank</code> method of <code>Instrument</code> and the
 167      * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.)

 168      * @param instrument instrument to load
 169      * @return <code>true</code> if the instrument is successfully loaded (or
 170      * already had been), <code>false</code> if the instrument could not be
 171      * loaded (for example, if the synthesizer has insufficient
 172      * memory to load it)
 173      * @throws IllegalArgumentException if this
 174      * <code>Synthesizer</code> doesn't support the specified instrument's
 175      * soundbank
 176      * @see #unloadInstrument
 177      * @see #loadInstruments
 178      * @see #loadAllInstruments
 179      * @see #remapInstrument
 180      * @see SoundbankResource#getSoundbank
 181      * @see MidiChannel#programChange(int, int)
 182      */
 183     public boolean loadInstrument(Instrument instrument);
 184 
 185 
 186     /**
 187      * Unloads a particular instrument.

 188      * @param instrument instrument to unload
 189      * @throws IllegalArgumentException if this
 190      * <code>Synthesizer</code> doesn't support the specified instrument's
 191      * soundbank
 192      * @see #loadInstrument
 193      * @see #unloadInstruments
 194      * @see #unloadAllInstruments
 195      * @see #getLoadedInstruments
 196      * @see #remapInstrument
 197      */
 198     public void unloadInstrument(Instrument instrument);
 199 
 200 
 201     /**
 202      * Remaps an instrument. Instrument <code>to</code> takes the
 203      * place of instrument <code>from</code>.<br>
 204      * For example, if <code>from</code> was located at bank number 2,
 205      * program number 11, remapping causes that bank and program location
 206      * to be occupied instead by <code>to</code>.<br>
 207      * If the function succeeds,  instrument <code>from</code> is unloaded.
 208      * <p>To cancel the remapping reload instrument <code>from</code> by
 209      * invoking one of {@link #loadInstrument}, {@link #loadInstruments}
 210      * or {@link #loadAllInstruments}.
 211      *
 212      * @param from the <code>Instrument</code> object to be replaced
 213      * @param to the <code>Instrument</code> object to be used in place
 214      * of the old instrument, it should be loaded into the synthesizer
 215      * @return <code>true</code> if the instrument successfully remapped,
 216      * <code>false</code> if feature is not implemented by synthesizer
 217      * @throws IllegalArgumentException if instrument
 218      * <code>from</code> or instrument <code>to</code> aren't supported by
 219      * synthesizer or if instrument <code>to</code> is not loaded
 220      * @throws NullPointerException if <code>from</code> or
 221      * <code>to</code> parameters have null value



 222      * @see #loadInstrument
 223      * @see #loadInstruments
 224      * @see #loadAllInstruments
 225      */
 226     public boolean remapInstrument(Instrument from, Instrument to);
 227 
 228 
 229     /**
 230      * Obtains the default soundbank for the synthesizer, if one exists.
 231      * (Some synthesizers provide a default or built-in soundbank.)
 232      * If a synthesizer doesn't have a default soundbank, instruments must
 233      * be loaded explicitly from an external soundbank.
 234      * @return default soundbank, or <code>null</code> if one does not exist.

 235      * @see #isSoundbankSupported
 236      */
 237     public Soundbank getDefaultSoundbank();
 238 
 239 
 240     /**
 241      * Obtains a list of instruments that come with the synthesizer.  These
 242      * instruments might be built into the synthesizer, or they might be
 243      * part of a default soundbank provided with the synthesizer, etc.
 244      * <p>
 245      * Note that you don't use this method  to find out which instruments are
 246      * currently loaded onto the synthesizer; for that purpose, you use
 247      * <code>getLoadedInstruments()</code>.
 248      * Nor does the method indicate all the instruments that can be loaded onto
 249      * the synthesizer; it only indicates the subset that come with the synthesizer.
 250      * To learn whether another instrument can be loaded, you can invoke
 251      * <code>isSoundbankSupported()</code>, and if the instrument's
 252      * <code>Soundbank</code> is supported, you can try loading the instrument.
 253      *
 254      * @return list of available instruments. If the synthesizer
 255      * has no instruments coming with it, an array of length 0 is returned.
 256      * @see #getLoadedInstruments
 257      * @see #isSoundbankSupported(Soundbank)
 258      * @see #loadInstrument
 259      */
 260     public Instrument[] getAvailableInstruments();
 261 
 262 
 263     /**
 264      * Obtains a list of the instruments that are currently loaded onto this
 265      * <code>Synthesizer</code>.

 266      * @return a list of currently loaded instruments
 267      * @see #loadInstrument
 268      * @see #getAvailableInstruments
 269      * @see Soundbank#getInstruments
 270      */
 271     public Instrument[] getLoadedInstruments();
 272 
 273 
 274     /**
 275      * Loads onto the <code>Synthesizer</code> all instruments contained
 276      * in the specified <code>Soundbank</code>.
 277      * @param soundbank the <code>Soundbank</code> whose are instruments are
 278      * to be loaded
 279      * @return <code>true</code> if the instruments are all successfully loaded (or
 280      * already had been), <code>false</code> if any instrument could not be
 281      * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)


 282      * @throws IllegalArgumentException if the requested soundbank is
 283      * incompatible with this synthesizer.
 284      * @see #isSoundbankSupported
 285      * @see #loadInstrument
 286      * @see #loadInstruments
 287      */
 288     public boolean loadAllInstruments(Soundbank soundbank);
 289 
 290 
 291 
 292     /**
 293      * Unloads all instruments contained in the specified <code>Soundbank</code>.

 294      * @param soundbank soundbank containing instruments to unload
 295      * @throws IllegalArgumentException thrown if the soundbank is not supported.
 296      * @see #isSoundbankSupported
 297      * @see #unloadInstrument
 298      * @see #unloadInstruments
 299      */
 300     public void unloadAllInstruments(Soundbank soundbank);
 301 
 302 
 303     /**
 304      * Loads the instruments referenced by the specified patches, from the
 305      * specified <code>Soundbank</code>.  Each of the <code>Patch</code> objects
 306      * indicates a bank and program number; the <code>Instrument</code> that
 307      * has the matching <code>Patch</code> is loaded into that bank and program
 308      * location.
 309      * @param soundbank the <code>Soundbank</code> containing the instruments to load

 310      * @param patchList list of patches for which instruments should be loaded
 311      * @return <code>true</code> if the instruments are all successfully loaded (or
 312      * already had been), <code>false</code> if any instrument could not be
 313      * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
 314      * @throws IllegalArgumentException thrown if the soundbank is not supported.

 315      * @see #isSoundbankSupported
 316      * @see Instrument#getPatch
 317      * @see #loadAllInstruments
 318      * @see #loadInstrument
 319      * @see Soundbank#getInstrument(Patch)
 320      * @see Sequence#getPatchList()
 321      */
 322     public boolean loadInstruments(Soundbank soundbank, Patch[] patchList);
 323 
 324     /**
 325      * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.
 326      * @param soundbank soundbank containing instruments to unload
 327      * @param patchList list of patches for which instruments should be unloaded
 328      * @throws IllegalArgumentException thrown if the soundbank is not supported.
 329      *




 330      * @see #unloadInstrument
 331      * @see #unloadAllInstruments
 332      * @see #isSoundbankSupported
 333      * @see Instrument#getPatch
 334      * @see #loadInstruments
 335      */
 336     public void unloadInstruments(Soundbank soundbank, Patch[] patchList);
 337 
 338 
 339     // RECEIVER METHODS
 340 
 341     /**
 342      * Obtains the name of the receiver.

 343      * @return receiver name
 344      */
 345     //  public abstract String getName();
 346 
 347 
 348     /**
 349      * Opens the receiver.

 350      * @throws MidiUnavailableException if the receiver is cannot be opened,
 351      * usually because the MIDI device is in use by another application.
 352      * @throws SecurityException if the receiver cannot be opened due to security
 353      * restrictions.
 354      */
 355     //  public abstract void open() throws MidiUnavailableException, SecurityException;
 356 
 357 
 358     /**
 359      * Closes the receiver.
 360      */
 361     //  public abstract void close();
 362 
 363 
 364     /**
 365      * Sends a MIDI event to the receiver.
 366      * @param event event to send.
 367      * @throws IllegalStateException if the receiver is not open.

 368      */
 369     //  public void send(MidiEvent event) throws IllegalStateException {
 370     //
 371     //  }
 372 
 373 
 374     /**
 375      * Obtains the set of controls supported by the
 376      * element.  If no controls are supported, returns an
 377      * array of length 0.
 378      * @return set of controls
 379      */
 380     // $$kk: 03.04.99: josh bloch recommends getting rid of this:
 381     // what can you really do with a set of untyped controls??
 382     // $$kk: 03.05.99: i am putting this back in.  for one thing,
 383     // you can check the length and know whether you should keep
 384     // looking....
 385     // public Control[] getControls();
 386 
 387     /**
 388      * Obtains the specified control.

 389      * @param controlClass class of the requested control
 390      * @return requested control object, or null if the
 391      * control is not supported.
 392      */
 393     // public Control getControl(Class controlClass);
 394 }
   1 /*
   2  * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.midi;
  27 



  28 /**
  29  * A {@code Synthesizer} generates sound. This usually happens when one of the
  30  * {@code Synthesizer}'s {@link MidiChannel} objects receives a
  31  * {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via
  32  * the {@code Synthesizer} object. Many {@code Synthesizer}s support
  33  * {@code Receivers}, through which MIDI events can be delivered to the
  34  * {@code Synthesizer}. In such cases, the {@code Synthesizer} typically
  35  * responds by sending a corresponding message to the appropriate
  36  * {@code MidiChannel}, or by processing the event itself if the event isn't one
  37  * of the MIDI channel messages.

  38  * <p>
  39  * The {@code Synthesizer} interface includes methods for loading and unloading
  40  * instruments from soundbanks. An instrument is a specification for
  41  * synthesizing a certain type of sound, whether that sound emulates a
  42  * traditional instrument or is some kind of sound effect or other imaginary
  43  * sound. A soundbank is a collection of instruments, organized by bank and
  44  * program number (via the instrument's {@code Patch} object). Different
  45  * {@code Synthesizer} classes might implement different sound-synthesis
  46  * techniques, meaning that some instruments and not others might be compatible
  47  * with a given synthesizer. Also, synthesizers may have a limited amount of
  48  * memory for instruments, meaning that not every soundbank and instrument can
  49  * be used by every synthesizer, even if the synthesis technique is compatible.
  50  * To see whether the instruments from a certain soundbank can be played by a
  51  * given synthesizer, invoke the
  52  * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported}
  53  * method of {@code Synthesizer}.
  54  * <p>
  55  * "Loading" an instrument means that that instrument becomes available for
  56  * synthesizing notes. The instrument is loaded into the bank and program
  57  * location specified by its {@code Patch} object. Loading does not necessarily
  58  * mean that subsequently played notes will immediately have the sound of this
  59  * newly loaded instrument. For the instrument to play notes, one of the
  60  * synthesizer's {@code MidiChannel} objects must receive (or have received) a
  61  * program-change message that causes that particular instrument's bank and
  62  * program number to be selected.
  63  *
  64  * @author Kara Kytle
  65  * @see MidiSystem#getSynthesizer
  66  * @see Soundbank
  67  * @see Instrument
  68  * @see MidiChannel#programChange(int, int)
  69  * @see Receiver
  70  * @see Transmitter
  71  * @see MidiDevice


  72  */
  73 public interface Synthesizer extends MidiDevice {
  74 

  75     // SYNTHESIZER METHODS
  76 

  77     /**
  78      * Obtains the maximum number of notes that this synthesizer can sound
  79      * simultaneously.
  80      *
  81      * @return the maximum number of simultaneous notes
  82      * @see #getVoiceStatus
  83      */
  84     int getMaxPolyphony();

  85 
  86     /**
  87      * Obtains the processing latency incurred by this synthesizer, expressed in
  88      * microseconds. This latency measures the worst-case delay between the time
  89      * a MIDI message is delivered to the synthesizer and the time that the
  90      * synthesizer actually produces the corresponding result.
  91      * <p>
  92      * Although the latency is expressed in microseconds, a synthesizer's actual
  93      * measured delay may vary over a wider range than this resolution suggests.
  94      * For example, a synthesizer might have a worst-case delay of a few
  95      * milliseconds or more.
  96      *
  97      * @return the worst-case delay, in microseconds
  98      */
  99     long getLatency();

 100 
 101     /**
 102      * Obtains the set of MIDI channels controlled by this synthesizer. Each
 103      * non-null element in the returned array is a {@code MidiChannel} that
 104      * receives the MIDI messages sent on that channel number.
 105      * <p>
 106      * The MIDI 1.0 specification provides for 16 channels, so this method
 107      * returns an array of at least 16 elements. However, if this synthesizer
 108      * doesn't make use of all 16 channels, some of the elements of the array
 109      * might be {@code null}, so you should check each element before using it.
 110      *
 111      * @return an array of the {@code MidiChannel} objects managed by this
 112      *         {@code Synthesizer}. Some of the array elements may be
 113      *         {@code null}.
 114      */
 115     MidiChannel[] getChannels();

 116 
 117     /**
 118      * Obtains the current status of the voices produced by this synthesizer. If
 119      * this class of {@code Synthesizer} does not provide voice information, the
 120      * returned array will always be of length 0. Otherwise, its length is
 121      * always equal to the total number of voices, as returned by
 122      * {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description
 123      * for an explanation of synthesizer voices.)
 124      *
 125      * @return an array of {@code VoiceStatus} objects that supply information
 126      *         about the corresponding synthesizer voices
 127      * @see #getMaxPolyphony
 128      * @see VoiceStatus
 129      */
 130     VoiceStatus[] getVoiceStatus();

 131 
 132     /**
 133      * Informs the caller whether this synthesizer is capable of loading
 134      * instruments from the specified soundbank. If the soundbank is
 135      * unsupported, any attempts to load instruments from it will result in an
 136      * {@code IllegalArgumentException}.
 137      *
 138      * @param  soundbank soundbank for which support is queried
 139      * @return {@code true} if the soundbank is supported, otherwise
 140      *         {@code false}
 141      * @see #loadInstruments
 142      * @see #loadAllInstruments
 143      * @see #unloadInstruments
 144      * @see #unloadAllInstruments
 145      * @see #getDefaultSoundbank
 146      */
 147     boolean isSoundbankSupported(Soundbank soundbank);

 148 
 149     /**
 150      * Makes a particular instrument available for synthesis. This instrument is
 151      * loaded into the patch location specified by its {@code Patch} object, so
 152      * that if a program-change message is received (or has been received) that
 153      * causes that patch to be selected, subsequent notes will be played using
 154      * the sound of {@code instrument}. If the specified instrument is already
 155      * loaded, this method does nothing and returns {@code true}.

 156      * <p>
 157      * The instrument must be part of a soundbank that this {@code Synthesizer}
 158      * supports. (To make sure, you can use the {@code getSoundbank} method of
 159      * {@code Instrument} and the {@code isSoundbankSupported} method of
 160      * {@code Synthesizer}.)
 161      *
 162      * @param  instrument instrument to load
 163      * @return {@code true} if the instrument is successfully loaded (or already
 164      *         had been), {@code false} if the instrument could not be loaded
 165      *         (for example, if the synthesizer has insufficient memory to load
 166      *         it)
 167      * @throws IllegalArgumentException if this {@code Synthesizer} doesn't
 168      *         support the specified instrument's soundbank

 169      * @see #unloadInstrument
 170      * @see #loadInstruments
 171      * @see #loadAllInstruments
 172      * @see #remapInstrument
 173      * @see SoundbankResource#getSoundbank
 174      * @see MidiChannel#programChange(int, int)
 175      */
 176     boolean loadInstrument(Instrument instrument);

 177 
 178     /**
 179      * Unloads a particular instrument.
 180      *
 181      * @param  instrument instrument to unload
 182      * @throws IllegalArgumentException if this {@code Synthesizer} doesn't
 183      *         support the specified instrument's soundbank

 184      * @see #loadInstrument
 185      * @see #unloadInstruments
 186      * @see #unloadAllInstruments
 187      * @see #getLoadedInstruments
 188      * @see #remapInstrument
 189      */
 190     void unloadInstrument(Instrument instrument);

 191 
 192     /**
 193      * Remaps an instrument. Instrument {@code to} takes the place of instrument
 194      * {@code from}.
 195      * <br>
 196      * For example, if {@code from} was located at bank number 2, program number
 197      * 11, remapping causes that bank and program location to be occupied
 198      * instead by {@code to}.
 199      * <br>
 200      * If the function succeeds, instrument {@code from} is unloaded.
 201      * <p>
 202      * To cancel the remapping reload instrument {@code from} by invoking one of
 203      * {@link #loadInstrument}, {@link #loadInstruments} or
 204      * {@link #loadAllInstruments}.
 205      *
 206      * @param  from the {@code Instrument} object to be replaced
 207      * @param  to the {@code Instrument} object to be used in place of the old
 208      *         instrument, it should be loaded into the synthesizer
 209      * @return {@code true} if the instrument successfully remapped,
 210      *         {@code false} if feature is not implemented by synthesizer
 211      * @throws IllegalArgumentException if instrument {@code from} or instrument
 212      *         {@code to} aren't supported by synthesizer or if instrument
 213      *         {@code to} is not loaded
 214      * @throws NullPointerException if {@code from} or {@code to} parameters
 215      *         have null value
 216      * @see #loadInstrument
 217      * @see #loadInstruments
 218      * @see #loadAllInstruments
 219      */
 220     boolean remapInstrument(Instrument from, Instrument to);

 221 
 222     /**
 223      * Obtains the default soundbank for the synthesizer, if one exists. (Some
 224      * synthesizers provide a default or built-in soundbank.) If a synthesizer
 225      * doesn't have a default soundbank, instruments must be loaded explicitly
 226      * from an external soundbank.
 227      *
 228      * @return default soundbank, or {@code null} if one does not exist
 229      * @see #isSoundbankSupported
 230      */
 231     Soundbank getDefaultSoundbank();

 232 
 233     /**
 234      * Obtains a list of instruments that come with the synthesizer. These
 235      * instruments might be built into the synthesizer, or they might be part of
 236      * a default soundbank provided with the synthesizer, etc.
 237      * <p>
 238      * Note that you don't use this method to find out which instruments are
 239      * currently loaded onto the synthesizer; for that purpose, you use
 240      * {@code getLoadedInstruments()}. Nor does the method indicate all the
 241      * instruments that can be loaded onto the synthesizer; it only indicates
 242      * the subset that come with the synthesizer. To learn whether another
 243      * instrument can be loaded, you can invoke {@code isSoundbankSupported()},
 244      * and if the instrument's {@code Soundbank} is supported, you can try
 245      * loading the instrument.
 246      *
 247      * @return list of available instruments. If the synthesizer has no
 248      *         instruments coming with it, an array of length 0 is returned.
 249      * @see #getLoadedInstruments
 250      * @see #isSoundbankSupported(Soundbank)
 251      * @see #loadInstrument
 252      */
 253     Instrument[] getAvailableInstruments();

 254 
 255     /**
 256      * Obtains a list of the instruments that are currently loaded onto this
 257      * {@code Synthesizer}.
 258      *
 259      * @return a list of currently loaded instruments
 260      * @see #loadInstrument
 261      * @see #getAvailableInstruments
 262      * @see Soundbank#getInstruments
 263      */
 264     Instrument[] getLoadedInstruments();

 265 
 266     /**
 267      * Loads onto the {@code Synthesizer} all instruments contained in the
 268      * specified {@code Soundbank}.
 269      *
 270      * @param  soundbank the {@code Soundbank} whose are instruments are to be
 271      *         loaded
 272      * @return {@code true} if the instruments are all successfully loaded (or
 273      *         already had been), {@code false} if any instrument could not be
 274      *         loaded (for example, if the {@code Synthesizer} had insufficient
 275      *         memory)
 276      * @throws IllegalArgumentException if the requested soundbank is
 277      *         incompatible with this synthesizer
 278      * @see #isSoundbankSupported
 279      * @see #loadInstrument
 280      * @see #loadInstruments
 281      */
 282     boolean loadAllInstruments(Soundbank soundbank);


 283 
 284     /**
 285      * Unloads all instruments contained in the specified {@code Soundbank}.
 286      *
 287      * @param  soundbank soundbank containing instruments to unload
 288      * @throws IllegalArgumentException thrown if the soundbank is not supported
 289      * @see #isSoundbankSupported
 290      * @see #unloadInstrument
 291      * @see #unloadInstruments
 292      */
 293     void unloadAllInstruments(Soundbank soundbank);

 294 
 295     /**
 296      * Loads the instruments referenced by the specified patches, from the
 297      * specified {@code Soundbank}. Each of the {@code Patch} objects indicates
 298      * a bank and program number; the {@code Instrument} that has the matching
 299      * {@code Patch} is loaded into that bank and program location.
 300      *
 301      * @param  soundbank the {@code Soundbank} containing the instruments to
 302      *         load
 303      * @param  patchList list of patches for which instruments should be loaded
 304      * @return {@code true} if the instruments are all successfully loaded (or
 305      *         already had been), {@code false} if any instrument could not be
 306      *         loaded (for example, if the {@code Synthesizer} had insufficient
 307      *         memory)
 308      * @throws IllegalArgumentException thrown if the soundbank is not supported
 309      * @see #isSoundbankSupported
 310      * @see Instrument#getPatch
 311      * @see #loadAllInstruments
 312      * @see #loadInstrument
 313      * @see Soundbank#getInstrument(Patch)
 314      * @see Sequence#getPatchList()
 315      */
 316     boolean loadInstruments(Soundbank soundbank, Patch[] patchList);
 317 
 318     /**
 319      * Unloads the instruments referenced by the specified patches, from the
 320      * MIDI sound bank specified.


 321      *
 322      * @param  soundbank soundbank containing instruments to unload
 323      * @param  patchList list of patches for which instruments should be
 324      *         unloaded
 325      * @throws IllegalArgumentException thrown if the soundbank is not supported
 326      * @see #unloadInstrument
 327      * @see #unloadAllInstruments
 328      * @see #isSoundbankSupported
 329      * @see Instrument#getPatch
 330      * @see #loadInstruments
 331      */
 332     void unloadInstruments(Soundbank soundbank, Patch[] patchList);

 333 
 334     // RECEIVER METHODS
 335 
 336     /**
 337      * Obtains the name of the receiver.
 338      *
 339      * @return receiver name
 340      */
 341     //  abstract String getName();

 342 
 343     /**
 344      * Opens the receiver.
 345      *
 346      * @throws MidiUnavailableException if the receiver is cannot be opened,
 347      *         usually because the MIDI device is in use by another application.
 348      * @throws SecurityException if the receiver cannot be opened due to
 349      *         security restrictions
 350      */
 351     //  abstract void open() throws MidiUnavailableException, SecurityException;

 352 
 353     /**
 354      * Closes the receiver.
 355      */
 356     //  abstract void close();

 357 
 358     /**
 359      * Sends a MIDI event to the receiver.
 360      *
 361      * @param  event event to send
 362      * @throws IllegalStateException if the receiver is not open
 363      */
 364     //  void send(MidiEvent event) throws IllegalStateException {
 365     //
 366     //  }
 367 

 368     /**
 369      * Obtains the set of controls supported by the element. If no controls are
 370      * supported, returns an array of length 0.
 371      *
 372      * @return set of controls
 373      */
 374     // $$kk: 03.04.99: josh bloch recommends getting rid of this:
 375     // what can you really do with a set of untyped controls??
 376     // $$kk: 03.05.99: i am putting this back in. for one thing,
 377     // you can check the length and know whether you should keep
 378     // looking....
 379     // Control[] getControls();
 380 
 381     /**
 382      * Obtains the specified control.
 383      *
 384      * @param  controlClass class of the requested control
 385      * @return requested control object, or null if the control is not supported

 386      */
 387     // Control getControl(Class controlClass);
 388 }