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

Print this page

        

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -23,372 +23,366 @@
  * questions.
  */
 
 package javax.sound.midi;
 
-import javax.sound.sampled.Control;
-
-
 /**
- * A <code>Synthesizer</code> generates sound.  This usually happens when one of
- * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a
- * {@link MidiChannel#noteOn(int, int) noteOn} message, either
- * directly or via the <code>Synthesizer</code> object.
- * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which
- * MIDI events can be delivered to the <code>Synthesizer</code>.
- * In such cases, the <code>Synthesizer</code> typically responds by sending
- * a corresponding message to the appropriate <code>MidiChannel</code>, or by
- * processing the event itself if the event isn't one of the MIDI channel
- * messages.
+ * A {@code Synthesizer} generates sound. This usually happens when one of the
+ * {@code Synthesizer}'s {@link MidiChannel} objects receives a
+ * {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via
+ * the {@code Synthesizer} object. Many {@code Synthesizer}s support
+ * {@code Receivers}, through which MIDI events can be delivered to the
+ * {@code Synthesizer}. In such cases, the {@code Synthesizer} typically
+ * responds by sending a corresponding message to the appropriate
+ * {@code MidiChannel}, or by processing the event itself if the event isn't one
+ * of the MIDI channel messages.
  * <p>
- * The <code>Synthesizer</code> interface includes methods for loading and
- * unloading instruments from soundbanks.  An instrument is a specification for synthesizing a
- * certain type of sound, whether that sound emulates a traditional instrument or is
- * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized
- * by bank and program number (via the instrument's <code>Patch</code> object).
- * Different <code>Synthesizer</code> classes might implement different sound-synthesis
- * techniques, meaning that some instruments and not others might be compatible with a
- * given synthesizer.
- * Also, synthesizers may have a limited amount of memory for instruments, meaning
- * that not every soundbank and instrument can be used by every synthesizer, even if
- * the synthesis technique is compatible.
- * To see whether the instruments from
- * a certain soundbank can be played by a given synthesizer, invoke the
- * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of
- * <code>Synthesizer</code>.
+ * The {@code Synthesizer} interface includes methods for loading and unloading
+ * instruments from soundbanks. An instrument is a specification for
+ * synthesizing a certain type of sound, whether that sound emulates a
+ * traditional instrument or is some kind of sound effect or other imaginary
+ * sound. A soundbank is a collection of instruments, organized by bank and
+ * program number (via the instrument's {@code Patch} object). Different
+ * {@code Synthesizer} classes might implement different sound-synthesis
+ * techniques, meaning that some instruments and not others might be compatible
+ * with a given synthesizer. Also, synthesizers may have a limited amount of
+ * memory for instruments, meaning that not every soundbank and instrument can
+ * be used by every synthesizer, even if the synthesis technique is compatible.
+ * To see whether the instruments from a certain soundbank can be played by a
+ * given synthesizer, invoke the
+ * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported}
+ * method of {@code Synthesizer}.
  * <p>
  * "Loading" an instrument means that that instrument becomes available for
- * synthesizing notes.  The instrument is loaded into the bank and
- * program location specified by its <code>Patch</code> object.  Loading does
- * not necessarily mean that subsequently played notes will immediately have
- * the sound of this newly loaded instrument.  For the instrument to play notes,
- * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received)
- * a program-change message that causes that particular instrument's
- * bank and program number to be selected.
+ * synthesizing notes. The instrument is loaded into the bank and program
+ * location specified by its {@code Patch} object. Loading does not necessarily
+ * mean that subsequently played notes will immediately have the sound of this
+ * newly loaded instrument. For the instrument to play notes, one of the
+ * synthesizer's {@code MidiChannel} objects must receive (or have received) a
+ * program-change message that causes that particular instrument's bank and
+ * program number to be selected.
  *
+ * @author Kara Kytle
  * @see MidiSystem#getSynthesizer
  * @see Soundbank
  * @see Instrument
  * @see MidiChannel#programChange(int, int)
  * @see Receiver
  * @see Transmitter
  * @see MidiDevice
- *
- * @author Kara Kytle
  */
 public interface Synthesizer extends MidiDevice {
 
-
     // SYNTHESIZER METHODS
 
-
     /**
-     * Obtains the maximum number of notes that this synthesizer can sound simultaneously.
+     * Obtains the maximum number of notes that this synthesizer can sound
+     * simultaneously.
+     *
      * @return the maximum number of simultaneous notes
      * @see #getVoiceStatus
      */
-    public int getMaxPolyphony();
-
+    int getMaxPolyphony();
 
     /**
      * Obtains the processing latency incurred by this synthesizer, expressed in
-     * microseconds.  This latency measures the worst-case delay between the
-     * time a MIDI message is delivered to the synthesizer and the time that the
+     * microseconds. This latency measures the worst-case delay between the time
+     * a MIDI message is delivered to the synthesizer and the time that the
      * synthesizer actually produces the corresponding result.
      * <p>
-     * Although the latency is expressed in microseconds, a synthesizer's actual measured
-     * delay may vary over a wider range than this resolution suggests.  For example,
-     * a synthesizer might have a worst-case delay of a few milliseconds or more.
+     * Although the latency is expressed in microseconds, a synthesizer's actual
+     * measured delay may vary over a wider range than this resolution suggests.
+     * For example, a synthesizer might have a worst-case delay of a few
+     * milliseconds or more.
      *
      * @return the worst-case delay, in microseconds
      */
-    public long getLatency();
-
+    long getLatency();
 
     /**
      * Obtains the set of MIDI channels controlled by this synthesizer.  Each
-     * non-null element in the returned array is a <code>MidiChannel</code> that
+     * non-null element in the returned array is a {@code MidiChannel} that
      * receives the MIDI messages sent on that channel number.
      * <p>
-     * The MIDI 1.0 specification provides for 16 channels, so this
-     * method returns an array of at least 16 elements.  However, if this synthesizer
+     * The MIDI 1.0 specification provides for 16 channels, so this method
+     * returns an array of at least 16 elements. However, if this synthesizer
      * doesn't make use of all 16 channels, some of the elements of the array
-     * might be <code>null</code>, so you should check each element
-     * before using it.
-     * @return an array of the <code>MidiChannel</code> objects managed by this
-     * <code>Synthesizer</code>.  Some of the array elements may be <code>null</code>.
+     * might be {@code null}, so you should check each element before using it.
+     *
+     * @return an array of the {@code MidiChannel} objects managed by this
+     *         {@code Synthesizer}. Some of the array elements may be
+     *         {@code null}.
      */
-    public MidiChannel[] getChannels();
-
+    MidiChannel[] getChannels();
 
     /**
-     * Obtains the current status of the voices produced by this synthesizer.
-     * If this class of <code>Synthesizer</code> does not provide voice
-     * information, the returned array will always be of length 0.  Otherwise,
-     * its length is always equal to the total number of voices, as returned by
-     * <code>getMaxPolyphony()</code>.  (See the <code>VoiceStatus</code> class
-     * description for an explanation of synthesizer voices.)
+     * Obtains the current status of the voices produced by this synthesizer. If
+     * this class of {@code Synthesizer} does not provide voice information, the
+     * returned array will always be of length 0. Otherwise, its length is
+     * always equal to the total number of voices, as returned by
+     * {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description
+     * for an explanation of synthesizer voices.)
      *
-     * @return an array of <code>VoiceStatus</code> objects that supply
-     * information about the corresponding synthesizer voices
+     * @return an array of {@code VoiceStatus} objects that supply information
+     *         about the corresponding synthesizer voices
      * @see #getMaxPolyphony
      * @see VoiceStatus
      */
-    public VoiceStatus[] getVoiceStatus();
-
+    VoiceStatus[] getVoiceStatus();
 
     /**
      * Informs the caller whether this synthesizer is capable of loading
-     * instruments from the specified soundbank.
-     * If the soundbank is unsupported, any attempts to load instruments from
-     * it will result in an <code>IllegalArgumentException</code>.
+     * instruments from the specified soundbank. If the soundbank is
+     * unsupported, any attempts to load instruments from it will result in an
+     * {@code IllegalArgumentException}.
+     *
      * @param soundbank soundbank for which support is queried
-     * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code>
+     * @return {@code true} if the soundbank is supported, otherwise
+     *         {@code false}
      * @see #loadInstruments
      * @see #loadAllInstruments
      * @see #unloadInstruments
      * @see #unloadAllInstruments
      * @see #getDefaultSoundbank
      */
-    public boolean isSoundbankSupported(Soundbank soundbank);
-
+    boolean isSoundbankSupported(Soundbank soundbank);
 
     /**
-     * Makes a particular instrument available for synthesis.  This instrument
-     * is loaded into the patch location specified by its <code>Patch</code>
-     * object, so that if a program-change message is
-     * received (or has been received) that causes that patch to be selected,
-     * subsequent notes will be played using the sound of
-     * <code>instrument</code>.  If the specified instrument is already loaded,
-     * this method does nothing and returns <code>true</code>.
+     * Makes a particular instrument available for synthesis. This instrument is
+     * loaded into the patch location specified by its {@code Patch} object, so
+     * that if a program-change message is received (or has been received) that
+     * causes that patch to be selected, subsequent notes will be played using
+     * the sound of {@code instrument}. If the specified instrument is already
+     * loaded, this method does nothing and returns {@code true}.
      * <p>
-     * The instrument must be part of a soundbank
-     * that this <code>Synthesizer</code> supports.  (To make sure, you can use
-     * the <code>getSoundbank</code> method of <code>Instrument</code> and the
-     * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.)
+     * The instrument must be part of a soundbank that this {@code Synthesizer}
+     * supports. (To make sure, you can use the {@code getSoundbank} method of
+     * {@code Instrument} and the {@code isSoundbankSupported} method of
+     * {@code Synthesizer}.)
+     *
      * @param instrument instrument to load
-     * @return <code>true</code> if the instrument is successfully loaded (or
-     * already had been), <code>false</code> if the instrument could not be
-     * loaded (for example, if the synthesizer has insufficient
-     * memory to load it)
-     * @throws IllegalArgumentException if this
-     * <code>Synthesizer</code> doesn't support the specified instrument's
-     * soundbank
+     * @return {@code true} if the instrument is successfully loaded (or already
+     *         had been), {@code false} if the instrument could not be loaded
+     *         (for example, if the synthesizer has insufficient memory to load
+     *         it)
+     * @throws IllegalArgumentException if this {@code Synthesizer} doesn't
+     *         support the specified instrument's soundbank
      * @see #unloadInstrument
      * @see #loadInstruments
      * @see #loadAllInstruments
      * @see #remapInstrument
      * @see SoundbankResource#getSoundbank
      * @see MidiChannel#programChange(int, int)
      */
-    public boolean loadInstrument(Instrument instrument);
-
+    boolean loadInstrument(Instrument instrument);
 
     /**
      * Unloads a particular instrument.
+     *
      * @param instrument instrument to unload
-     * @throws IllegalArgumentException if this
-     * <code>Synthesizer</code> doesn't support the specified instrument's
-     * soundbank
+     * @throws IllegalArgumentException if this {@code Synthesizer} doesn't
+     *         support the specified instrument's soundbank
      * @see #loadInstrument
      * @see #unloadInstruments
      * @see #unloadAllInstruments
      * @see #getLoadedInstruments
      * @see #remapInstrument
      */
-    public void unloadInstrument(Instrument instrument);
-
+    void unloadInstrument(Instrument instrument);
 
     /**
-     * Remaps an instrument. Instrument <code>to</code> takes the
-     * place of instrument <code>from</code>.<br>
-     * For example, if <code>from</code> was located at bank number 2,
-     * program number 11, remapping causes that bank and program location
-     * to be occupied instead by <code>to</code>.<br>
-     * If the function succeeds,  instrument <code>from</code> is unloaded.
-     * <p>To cancel the remapping reload instrument <code>from</code> by
-     * invoking one of {@link #loadInstrument}, {@link #loadInstruments}
-     * or {@link #loadAllInstruments}.
-     *
-     * @param from the <code>Instrument</code> object to be replaced
-     * @param to the <code>Instrument</code> object to be used in place
-     * of the old instrument, it should be loaded into the synthesizer
-     * @return <code>true</code> if the instrument successfully remapped,
-     * <code>false</code> if feature is not implemented by synthesizer
-     * @throws IllegalArgumentException if instrument
-     * <code>from</code> or instrument <code>to</code> aren't supported by
-     * synthesizer or if instrument <code>to</code> is not loaded
-     * @throws NullPointerException if <code>from</code> or
-     * <code>to</code> parameters have null value
+     * Remaps an instrument. Instrument {@code to} takes the place of instrument
+     * {@code from}.
+     * <br>
+     * For example, if {@code from} was located at bank number 2, program number
+     * 11, remapping causes that bank and program location to be occupied
+     * instead by {@code to}.
+     * <br>
+     * If the function succeeds, instrument {@code from} is unloaded.
+     * <p>
+     * To cancel the remapping reload instrument {@code from} by invoking one of
+     * {@link #loadInstrument}, {@link #loadInstruments} or
+     * {@link #loadAllInstruments}.
+     *
+     * @param  from the {@code Instrument} object to be replaced
+     * @param  to the {@code Instrument} object to be used in place of the old
+     *         instrument, it should be loaded into the synthesizer
+     * @return {@code true} if the instrument successfully remapped,
+     *         {@code false} if feature is not implemented by synthesizer
+     * @throws IllegalArgumentException if instrument {@code from} or instrument
+     *         {@code to} aren't supported by synthesizer or if instrument
+     *         {@code to} is not loaded
+     * @throws NullPointerException if {@code from} or {@code to} parameters
+     *         have null value
      * @see #loadInstrument
      * @see #loadInstruments
      * @see #loadAllInstruments
      */
-    public boolean remapInstrument(Instrument from, Instrument to);
-
+    boolean remapInstrument(Instrument from, Instrument to);
 
     /**
-     * Obtains the default soundbank for the synthesizer, if one exists.
-     * (Some synthesizers provide a default or built-in soundbank.)
-     * If a synthesizer doesn't have a default soundbank, instruments must
-     * be loaded explicitly from an external soundbank.
-     * @return default soundbank, or <code>null</code> if one does not exist.
+     * Obtains the default soundbank for the synthesizer, if one exists. (Some
+     * synthesizers provide a default or built-in soundbank.) If a synthesizer
+     * doesn't have a default soundbank, instruments must be loaded explicitly
+     * from an external soundbank.
+     *
+     * @return default soundbank, or {@code null} if one does not exist
      * @see #isSoundbankSupported
      */
-    public Soundbank getDefaultSoundbank();
-
+    Soundbank getDefaultSoundbank();
 
     /**
      * Obtains a list of instruments that come with the synthesizer.  These
-     * instruments might be built into the synthesizer, or they might be
-     * part of a default soundbank provided with the synthesizer, etc.
+     * instruments might be built into the synthesizer, or they might be part of
+     * a default soundbank provided with the synthesizer, etc.
      * <p>
      * Note that you don't use this method  to find out which instruments are
      * currently loaded onto the synthesizer; for that purpose, you use
-     * <code>getLoadedInstruments()</code>.
-     * Nor does the method indicate all the instruments that can be loaded onto
-     * the synthesizer; it only indicates the subset that come with the synthesizer.
-     * To learn whether another instrument can be loaded, you can invoke
-     * <code>isSoundbankSupported()</code>, and if the instrument's
-     * <code>Soundbank</code> is supported, you can try loading the instrument.
+     * {@code getLoadedInstruments()}. Nor does the method indicate all the
+     * instruments that can be loaded onto the synthesizer; it only indicates
+     * the subset that come with the synthesizer. To learn whether another
+     * instrument can be loaded, you can invoke {@code isSoundbankSupported()},
+     * and if the instrument's {@code Soundbank} is supported, you can try
+     * loading the instrument.
      *
-     * @return list of available instruments. If the synthesizer
-     * has no instruments coming with it, an array of length 0 is returned.
+     * @return list of available instruments. If the synthesizer has no
+     *         instruments coming with it, an array of length 0 is returned.
      * @see #getLoadedInstruments
      * @see #isSoundbankSupported(Soundbank)
      * @see #loadInstrument
      */
-    public Instrument[] getAvailableInstruments();
-
+    Instrument[] getAvailableInstruments();
 
     /**
      * Obtains a list of the instruments that are currently loaded onto this
-     * <code>Synthesizer</code>.
+     * {@code Synthesizer}.
+     *
      * @return a list of currently loaded instruments
      * @see #loadInstrument
      * @see #getAvailableInstruments
      * @see Soundbank#getInstruments
      */
-    public Instrument[] getLoadedInstruments();
-
+    Instrument[] getLoadedInstruments();
 
     /**
-     * Loads onto the <code>Synthesizer</code> all instruments contained
-     * in the specified <code>Soundbank</code>.
-     * @param soundbank the <code>Soundbank</code> whose are instruments are
-     * to be loaded
-     * @return <code>true</code> if the instruments are all successfully loaded (or
-     * already had been), <code>false</code> if any instrument could not be
-     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
+     * Loads onto the {@code Synthesizer} all instruments contained in the
+     * specified {@code Soundbank}.
+     *
+     * @param  soundbank the {@code Soundbank} whose are instruments are to be
+     *         loaded
+     * @return {@code true} if the instruments are all successfully loaded (or
+     *         already had been), {@code false} if any instrument could not be
+     *         loaded (for example, if the {@code Synthesizer} had insufficient
+     *         memory)
      * @throws IllegalArgumentException if the requested soundbank is
-     * incompatible with this synthesizer.
+     *         incompatible with this synthesizer
      * @see #isSoundbankSupported
      * @see #loadInstrument
      * @see #loadInstruments
      */
-    public boolean loadAllInstruments(Soundbank soundbank);
-
-
+    boolean loadAllInstruments(Soundbank soundbank);
 
     /**
-     * Unloads all instruments contained in the specified <code>Soundbank</code>.
+     * Unloads all instruments contained in the specified {@code Soundbank}.
+     *
      * @param soundbank soundbank containing instruments to unload
-     * @throws IllegalArgumentException thrown if the soundbank is not supported.
+     * @throws IllegalArgumentException thrown if the soundbank is not supported
      * @see #isSoundbankSupported
      * @see #unloadInstrument
      * @see #unloadInstruments
      */
-    public void unloadAllInstruments(Soundbank soundbank);
-
+    void unloadAllInstruments(Soundbank soundbank);
 
     /**
      * Loads the instruments referenced by the specified patches, from the
-     * specified <code>Soundbank</code>.  Each of the <code>Patch</code> objects
-     * indicates a bank and program number; the <code>Instrument</code> that
-     * has the matching <code>Patch</code> is loaded into that bank and program
-     * location.
-     * @param soundbank the <code>Soundbank</code> containing the instruments to load
+     * specified {@code Soundbank}. Each of the {@code Patch} objects indicates
+     * a bank and program number; the {@code Instrument} that has the matching
+     * {@code Patch} is loaded into that bank and program location.
+     *
+     * @param  soundbank the {@code Soundbank} containing the instruments to
+     *         load
      * @param patchList list of patches for which instruments should be loaded
-     * @return <code>true</code> if the instruments are all successfully loaded (or
-     * already had been), <code>false</code> if any instrument could not be
-     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
-     * @throws IllegalArgumentException thrown if the soundbank is not supported.
+     * @return {@code true} if the instruments are all successfully loaded (or
+     *         already had been), {@code false} if any instrument could not be
+     *         loaded (for example, if the {@code Synthesizer} had insufficient
+     *         memory)
+     * @throws IllegalArgumentException thrown if the soundbank is not supported
      * @see #isSoundbankSupported
      * @see Instrument#getPatch
      * @see #loadAllInstruments
      * @see #loadInstrument
      * @see Soundbank#getInstrument(Patch)
      * @see Sequence#getPatchList()
      */
-    public boolean loadInstruments(Soundbank soundbank, Patch[] patchList);
+    boolean loadInstruments(Soundbank soundbank, Patch[] patchList);
 
     /**
-     * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.
-     * @param soundbank soundbank containing instruments to unload
-     * @param patchList list of patches for which instruments should be unloaded
-     * @throws IllegalArgumentException thrown if the soundbank is not supported.
+     * Unloads the instruments referenced by the specified patches, from the
+     * MIDI sound bank specified.
      *
+     * @param  soundbank soundbank containing instruments to unload
+     * @param  patchList list of patches for which instruments should be
+     *         unloaded
+     * @throws IllegalArgumentException thrown if the soundbank is not supported
      * @see #unloadInstrument
      * @see #unloadAllInstruments
      * @see #isSoundbankSupported
      * @see Instrument#getPatch
      * @see #loadInstruments
      */
-    public void unloadInstruments(Soundbank soundbank, Patch[] patchList);
-
+    void unloadInstruments(Soundbank soundbank, Patch[] patchList);
 
     // RECEIVER METHODS
 
     /**
      * Obtains the name of the receiver.
+     *
      * @return receiver name
      */
-    //  public abstract String getName();
-
+    //  abstract String getName();
 
     /**
      * Opens the receiver.
+     *
      * @throws MidiUnavailableException if the receiver is cannot be opened,
      * usually because the MIDI device is in use by another application.
-     * @throws SecurityException if the receiver cannot be opened due to security
-     * restrictions.
+     * @throws SecurityException if the receiver cannot be opened due to
+     *         security restrictions
      */
-    //  public abstract void open() throws MidiUnavailableException, SecurityException;
-
+    //  abstract void open() throws MidiUnavailableException, SecurityException;
 
     /**
      * Closes the receiver.
      */
-    //  public abstract void close();
-
+    //  abstract void close();
 
     /**
      * Sends a MIDI event to the receiver.
-     * @param event event to send.
-     * @throws IllegalStateException if the receiver is not open.
+     *
+     * @param  event event to send
+     * @throws IllegalStateException if the receiver is not open
      */
-    //  public void send(MidiEvent event) throws IllegalStateException {
+    //  void send(MidiEvent event) throws IllegalStateException {
     //
     //  }
 
-
     /**
-     * Obtains the set of controls supported by the
-     * element.  If no controls are supported, returns an
-     * array of length 0.
+     * Obtains the set of controls supported by the element. If no controls are
+     * supported, returns an array of length 0.
+     *
      * @return set of controls
      */
     // $$kk: 03.04.99: josh bloch recommends getting rid of this:
     // what can you really do with a set of untyped controls??
     // $$kk: 03.05.99: i am putting this back in.  for one thing,
     // you can check the length and know whether you should keep
     // looking....
-    // public Control[] getControls();
+    // Control[] getControls();
 
     /**
      * Obtains the specified control.
+     *
      * @param controlClass class of the requested control
-     * @return requested control object, or null if the
-     * control is not supported.
+     * @return requested control object, or null if the control is not supported
      */
-    // public Control getControl(Class controlClass);
+    // Control getControl(Class controlClass);
 }