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 import java.io.File;
  29 import java.io.IOException;
  30 import java.io.InputStream;
  31 import java.io.OutputStream;
  32 import java.net.URL;

  33 import java.util.ArrayList;
  34 import java.util.HashSet;
  35 import java.util.Iterator;
  36 import java.util.List;
  37 import java.util.Properties;
  38 import java.util.Set;
  39 
  40 import javax.sound.midi.spi.MidiDeviceProvider;


  41 import javax.sound.midi.spi.MidiFileReader;
  42 import javax.sound.midi.spi.MidiFileWriter;
  43 import javax.sound.midi.spi.SoundbankReader;

  44 


  45 import com.sun.media.sound.AutoConnectSequencer;
  46 import com.sun.media.sound.JDK13Services;
  47 import com.sun.media.sound.MidiDeviceReceiverEnvelope;
  48 import com.sun.media.sound.MidiDeviceTransmitterEnvelope;
  49 import com.sun.media.sound.ReferenceCountingDevice;
  50 
  51 /**
  52  * The {@code MidiSystem} class provides access to the installed MIDI system
  53  * resources, including devices such as synthesizers, sequencers, and MIDI input
  54  * and output ports. A typical simple MIDI application might begin by invoking
  55  * one or more {@code MidiSystem} methods to learn what devices are installed
  56  * and to obtain the ones needed in that application.
  57  * <p>
  58  * The class also has methods for reading files, streams, and  URLs that contain
  59  * standard MIDI file data or soundbanks. You can query the {@code MidiSystem}
  60  * for the format of a specified MIDI file.
  61  * <p>
  62  * You cannot instantiate a {@code MidiSystem}; all the methods are static.
  63  * <p>
  64  * Properties can be used to specify default MIDI devices. Both system
  65  * properties and a properties file are considered. The "sound.properties"
  66  * properties file is read from an implementation-specific location (typically
  67  * it is the {@code lib} directory in the Java installation directory). If a
  68  * property exists both as a system property and in the properties file, the
  69  * system property takes precedence. If none is specified, a suitable default is
  70  * chosen among the available devices. The syntax of the properties file is
  71  * specified in {@link Properties#load(InputStream) Properties.load}. The
  72  * following table lists the available property keys and which methods consider
  73  * them:




  74  *
  75  * <table border=0>
  76  *  <caption>MIDI System Property Keys</caption>
  77  *  <tr>
  78  *   <th>Property Key</th>
  79  *   <th>Interface</th>
  80  *   <th>Affected Method</th>
  81  *  </tr>
  82  *  <tr>
  83  *   <td>{@code javax.sound.midi.Receiver}</td>
  84  *   <td>{@link Receiver}</td>
  85  *   <td>{@link #getReceiver}</td>
  86  *  </tr>
  87  *  <tr>
  88  *   <td>{@code javax.sound.midi.Sequencer}</td>
  89  *   <td>{@link Sequencer}</td>
  90  *   <td>{@link #getSequencer}</td>
  91  *  </tr>
  92  *  <tr>
  93  *   <td>{@code javax.sound.midi.Synthesizer}</td>
  94  *   <td>{@link Synthesizer}</td>
  95  *   <td>{@link #getSynthesizer}</td>
  96  *  </tr>
  97  *  <tr>
  98  *   <td>{@code javax.sound.midi.Transmitter}</td>
  99  *   <td>{@link Transmitter}</td>
 100  *   <td>{@link #getTransmitter}</td>
 101  *  </tr>
 102  * </table>
 103  *
 104  * The property value consists of the provider class name and the device name,
 105  * separated by the hash mark (&quot;#&quot;). The provider class name is the
 106  * fully-qualified name of a concrete
 107  * {@link MidiDeviceProvider MIDI device provider} class. The device name is
 108  * matched against the {@code String} returned by the {@code getName} method of
 109  * {@code MidiDevice.Info}. Either the class name, or the device name may be
 110  * omitted. If only the class name is specified, the trailing hash mark is
 111  * optional.
 112  * <p>
 113  * If the provider class is specified, and it can be successfully retrieved from
 114  * the installed providers, the list of {@code MidiDevice.Info} objects is
 115  * retrieved from the provider. Otherwise, or when these devices do not provide
 116  * a subsequent match, the list is retrieved from {@link #getMidiDeviceInfo} to
 117  * contain all available {@code MidiDevice.Info} objects.
 118  * <p>
 119  * If a device name is specified, the resulting list of {@code MidiDevice.Info}
 120  * objects is searched: the first one with a matching name, and whose
 121  * {@code MidiDevice} implements the respective interface, will be returned. If
 122  * no matching {@code MidiDevice.Info} object is found, or the device name is
 123  * not specified, the first suitable device from the resulting list will be
 124  * returned. For Sequencer and Synthesizer, a device is suitable if it
 125  * implements the respective interface; whereas for Receiver and Transmitter, a
 126  * device is suitable if it implements neither Sequencer nor Synthesizer and
 127  * provides at least one Receiver or Transmitter, respectively.
 128  * <p>
 129  * For example, the property {@code javax.sound.midi.Receiver} with a value
 130  * {@code "com.sun.media.sound.MidiProvider#SunMIDI1"} will have the following
 131  * consequences when {@code getReceiver} is called: if the class
 132  * {@code com.sun.media.sound.MidiProvider} exists in the list of installed MIDI
 133  * device providers, the first {@code Receiver} device with name
 134  * {@code "SunMIDI1"} will be returned. If it cannot be found, the first
 135  * {@code Receiver} from that provider will be returned, regardless of name. If
 136  * there is none, the first {@code Receiver} with name {@code "SunMIDI1"} in the
 137  * list of all devices (as returned by {@code getMidiDeviceInfo}) will be
 138  * returned, or, if not found, the first {@code Receiver} that can be found in
 139  * the list of all devices is returned. If that fails, too, a
 140  * {@code MidiUnavailableException} is thrown.
















 141  *
 142  * @author Kara Kytle
 143  * @author Florian Bomers
 144  * @author Matthias Pfisterer
 145  */
 146 public class MidiSystem {
 147 
 148     /**
 149      * Private no-args constructor for ensuring against instantiation.
 150      */
 151     private MidiSystem() {
 152     }
 153 

 154     /**
 155      * Obtains an array of information objects representing the set of all MIDI
 156      * devices available on the system. A returned information object can then
 157      * be used to obtain the corresponding device object, by invoking

 158      * {@link #getMidiDevice(MidiDevice.Info) getMidiDevice}.
 159      *
 160      * @return an array of {@code MidiDevice.Info} objects, one for each
 161      *         installed MIDI device. If no such devices are installed, an array
 162      *         of length 0 is returned.
 163      */
 164     public static MidiDevice.Info[] getMidiDeviceInfo() {
 165         List<MidiDevice.Info> allInfos = new ArrayList<>();
 166         List<MidiDeviceProvider> providers = getMidiDeviceProviders();
 167 
 168         for(int i = 0; i < providers.size(); i++) {
 169             MidiDeviceProvider provider = providers.get(i);
 170             MidiDevice.Info[] tmpinfo = provider.getDeviceInfo();
 171             for (int j = 0; j < tmpinfo.length; j++) {
 172                 allInfos.add( tmpinfo[j] );
 173             }
 174         }
 175         MidiDevice.Info[] infosArray = allInfos.toArray(new MidiDevice.Info[0]);
 176         return infosArray;
 177     }
 178 

 179     /**
 180      * Obtains the requested MIDI device.
 181      *
 182      * @param  info a device information object representing the desired device
 183      * @return the requested device
 184      * @throws MidiUnavailableException if the requested device is not available
 185      *         due to resource restrictions
 186      * @throws IllegalArgumentException if the info object does not represent a
 187      *         MIDI device installed on the system
 188      * @see #getMidiDeviceInfo
 189      */
 190     public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException {
 191         List<MidiDeviceProvider> providers = getMidiDeviceProviders();
 192 
 193         for(int i = 0; i < providers.size(); i++) {
 194             MidiDeviceProvider provider = providers.get(i);
 195             if (provider.isDeviceSupported(info)) {
 196                 MidiDevice device = provider.getDevice(info);
 197                 return device;
 198             }
 199         }
 200         throw new IllegalArgumentException("Requested device not installed: " + info);
 201     }
 202 

 203     /**
 204      * Obtains a MIDI receiver from an external MIDI port or other default
 205      * device. The returned receiver always implements the
 206      * {@code MidiDeviceReceiver} interface.
 207      * <p>
 208      * If the system property {@code javax.sound.midi.Receiver} is defined or it
 209      * is defined in the file "sound.properties", it is used to identify the
 210      * device that provides the default receiver. For details, refer to the
 211      * {@link MidiSystem class description}.
 212      * <p>
 213      * If a suitable MIDI port is not available, the Receiver is retrieved from
 214      * an installed synthesizer.
 215      * <p>
 216      * If a native receiver provided by the default device does not implement
 217      * the {@code MidiDeviceReceiver} interface, it will be wrapped in a wrapper
 218      * class that implements the {@code MidiDeviceReceiver} interface. The
 219      * corresponding {@code Receiver} method calls will be forwarded to the
 220      * native receiver.
 221      * <p>
 222      * If this method returns successfully, the {@link MidiDevice MidiDevice}
 223      * the {@code Receiver} belongs to is opened implicitly, if it is not
 224      * already open. It is possible to close an implicitly opened device by
 225      * calling {@link Receiver#close close} on the returned {@code Receiver}.
 226      * All open {@code Receiver} instances have to be closed in order to release
 227      * system resources hold by the {@code MidiDevice}. For a detailed
 228      * description of open/close behaviour see the class description of
 229      * {@link MidiDevice MidiDevice}.





 230      *
 231      * @return the default MIDI receiver
 232      * @throws MidiUnavailableException if the default receiver is not available
 233      *         due to resource restrictions, or no device providing receivers is
 234      *         installed in the system
 235      */
 236     public static Receiver getReceiver() throws MidiUnavailableException {
 237         // may throw MidiUnavailableException
 238         MidiDevice device = getDefaultDeviceWrapper(Receiver.class);
 239         Receiver receiver;
 240         if (device instanceof ReferenceCountingDevice) {
 241             receiver = ((ReferenceCountingDevice) device).getReceiverReferenceCounting();
 242         } else {
 243             receiver = device.getReceiver();
 244         }
 245         if (!(receiver instanceof MidiDeviceReceiver)) {
 246             receiver = new MidiDeviceReceiverEnvelope(device, receiver);
 247         }
 248         return receiver;
 249     }
 250 

 251     /**
 252      * Obtains a MIDI transmitter from an external MIDI port or other default
 253      * source. The returned transmitter always implements the
 254      * {@code MidiDeviceTransmitter} interface.
 255      * <p>
 256      * If the system property {@code javax.sound.midi.Transmitter} is defined or
 257      * it is defined in the file "sound.properties", it is used to identify the
 258      * device that provides the default transmitter. For details, refer to the
 259      * {@link MidiSystem class description}.
 260      * <p>
 261      * If a native transmitter provided by the default device does not implement


 262      * the {@code MidiDeviceTransmitter} interface, it will be wrapped in a
 263      * wrapper class that implements the {@code MidiDeviceTransmitter}
 264      * interface. The corresponding {@code Transmitter} method calls will be
 265      * forwarded to the native transmitter.
 266      * <p>
 267      * If this method returns successfully, the {@link MidiDevice MidiDevice}
 268      * the {@code Transmitter} belongs to is opened implicitly, if it is not
 269      * already open. It is possible to close an implicitly opened device by
 270      * calling {@link Transmitter#close close} on the returned
 271      * {@code Transmitter}. All open {@code Transmitter} instances have to be
 272      * closed in order to release system resources hold by the
 273      * {@code MidiDevice}. For a detailed description of open/close behaviour
 274      * see the class description of {@link MidiDevice MidiDevice}.



 275      *
 276      * @return the default MIDI transmitter
 277      * @throws MidiUnavailableException if the default transmitter is not
 278      *         available due to resource restrictions, or no device providing
 279      *         transmitters is installed in the system
 280      */
 281     public static Transmitter getTransmitter() throws MidiUnavailableException {
 282         // may throw MidiUnavailableException
 283         MidiDevice device = getDefaultDeviceWrapper(Transmitter.class);
 284         Transmitter transmitter;
 285         if (device instanceof ReferenceCountingDevice) {
 286             transmitter = ((ReferenceCountingDevice) device).getTransmitterReferenceCounting();
 287         } else {
 288             transmitter = device.getTransmitter();
 289         }
 290         if (!(transmitter instanceof MidiDeviceTransmitter)) {
 291             transmitter = new MidiDeviceTransmitterEnvelope(device, transmitter);
 292         }
 293         return transmitter;
 294     }
 295 

 296     /**
 297      * Obtains the default synthesizer.
 298      * <p>
 299      * If the system property {@code javax.sound.midi.Synthesizer} is defined or
 300      * it is defined in the file "sound.properties", it is used to identify the
 301      * default synthesizer. For details, refer to the
 302      * {@link MidiSystem class description}.

 303      *
 304      * @return the default synthesizer
 305      * @throws MidiUnavailableException if the synthesizer is not available due
 306      *         to resource restrictions, or no synthesizer is installed in the
 307      *         system
 308      */
 309     public static Synthesizer getSynthesizer() throws MidiUnavailableException {
 310         // may throw MidiUnavailableException
 311         return (Synthesizer) getDefaultDeviceWrapper(Synthesizer.class);
 312     }
 313 

 314     /**
 315      * Obtains the default {@code Sequencer}, connected to a default device. The
 316      * returned {@code Sequencer} instance is connected to the default
 317      * {@code Synthesizer}, as returned by {@link #getSynthesizer}. If there is
 318      * no {@code Synthesizer} available, or the default {@code Synthesizer}
 319      * cannot be opened, the {@code sequencer} is connected to the default
 320      * {@code Receiver}, as returned by {@link #getReceiver}. The connection is
 321      * made by retrieving a {@code Transmitter} instance from the
 322      * {@code Sequencer} and setting its {@code Receiver}. Closing and
 323      * re-opening the sequencer will restore the connection to the default
 324      * device.
 325      * <p>
 326      * This method is equivalent to calling {@code getSequencer(true)}.
 327      * <p>
 328      * If the system property {@code javax.sound.midi.Sequencer} is defined or
 329      * it is defined in the file "sound.properties", it is used to identify the
 330      * default sequencer. For details, refer to the
 331      * {@link MidiSystem class description}.







 332      *
 333      * @return the default sequencer, connected to a default Receiver
 334      * @throws MidiUnavailableException if the sequencer is not available due to
 335      *         resource restrictions, or there is no {@code Receiver} available
 336      *         by any installed {@code MidiDevice}, or no sequencer is installed
 337      *         in the system

 338      * @see #getSequencer(boolean)
 339      * @see #getSynthesizer
 340      * @see #getReceiver
 341      */
 342     public static Sequencer getSequencer() throws MidiUnavailableException {
 343         return getSequencer(true);
 344     }
 345 


 346     /**
 347      * Obtains the default {@code Sequencer}, optionally connected to a default
 348      * device.
 349      * <p>
 350      * If {@code connected} is true, the returned {@code Sequencer} instance is
 351      * connected to the default {@code Synthesizer}, as returned by
 352      * {@link #getSynthesizer}. If there is no {@code Synthesizer} available, or
 353      * the default {@code Synthesizer} cannot be opened, the {@code sequencer}
 354      * is connected to the default {@code Receiver}, as returned by
 355      * {@link #getReceiver}. The connection is made by retrieving a
 356      * {@code Transmitter} instance from the {@code Sequencer} and setting its
 357      * {@code Receiver}. Closing and re-opening the sequencer will restore the





 358      * connection to the default device.
 359      * <p>
 360      * If {@code connected} is false, the returned {@code Sequencer} instance is
 361      * not connected, it has no open {@code Transmitters}. In order to play the
 362      * sequencer on a MIDI device, or a {@code Synthesizer}, it is necessary to
 363      * get a {@code Transmitter} and set its {@code Receiver}.
 364      * <p>
 365      * If the system property {@code javax.sound.midi.Sequencer} is defined or
 366      * it is defined in the file "sound.properties", it is used to identify the
 367      * default sequencer. For details, refer to the
 368      * {@link MidiSystem class description}.
 369      *
 370      * @param  connected whether or not the returned {@code Sequencer} is
 371      *         connected to the default {@code Synthesizer}













 372      * @return the default sequencer
 373      * @throws MidiUnavailableException if the sequencer is not available due to
 374      *         resource restrictions, or no sequencer is installed in the
 375      *         system, or if {@code connected} is true, and there is no
 376      *         {@code Receiver} available by any installed {@code MidiDevice}


 377      * @see #getSynthesizer
 378      * @see #getReceiver
 379      * @since 1.5
 380      */
 381     public static Sequencer getSequencer(boolean connected)
 382         throws MidiUnavailableException {
 383         Sequencer seq = (Sequencer) getDefaultDeviceWrapper(Sequencer.class);
 384 
 385         if (connected) {
 386             // IMPORTANT: this code needs to be synch'ed with
 387             //            all AutoConnectSequencer instances,
 388             //            (e.g. RealTimeSequencer) because the
 389             //            same algorithm for synth retrieval
 390             //            needs to be used!
 391 
 392             Receiver rec = null;
 393             MidiUnavailableException mue = null;
 394 
 395             // first try to connect to the default synthesizer
 396             try {
 397                 Synthesizer synth = getSynthesizer();
 398                 if (synth instanceof ReferenceCountingDevice) {
 399                     rec = ((ReferenceCountingDevice) synth).getReceiverReferenceCounting();
 400                 } else {
 401                     synth.open();
 402                     try {
 403                         rec = synth.getReceiver();
 404                     } finally {
 405                         // make sure that the synth is properly closed
 406                         if (rec == null) {
 407                             synth.close();
 408                         }
 409                     }
 410                 }
 411             } catch (MidiUnavailableException e) {
 412                 // something went wrong with synth
 413                 if (e instanceof MidiUnavailableException) {
 414                     mue = e;
 415                 }
 416             }
 417             if (rec == null) {
 418                 // then try to connect to the default Receiver
 419                 try {
 420                     rec = MidiSystem.getReceiver();
 421                 } catch (Exception e) {
 422                     // something went wrong. Nothing to do then!
 423                     if (e instanceof MidiUnavailableException) {
 424                         mue = (MidiUnavailableException) e;
 425                     }
 426                 }
 427             }
 428             if (rec != null) {
 429                 seq.getTransmitter().setReceiver(rec);
 430                 if (seq instanceof AutoConnectSequencer) {
 431                     ((AutoConnectSequencer) seq).setAutoConnect(rec);
 432                 }
 433             } else {
 434                 if (mue != null) {
 435                     throw mue;
 436                 }
 437                 throw new MidiUnavailableException("no receiver available");
 438             }
 439         }
 440         return seq;
 441     }
 442 



 443     /**
 444      * Constructs a MIDI sound bank by reading it from the specified stream. The
 445      * stream must point to a valid MIDI soundbank file. In general, MIDI
 446      * soundbank providers may need to read some data from the stream before
 447      * determining whether they support it. These parsers must be able to mark
 448      * the stream, read enough data to determine whether they support the
 449      * stream, and, if not, reset the stream's read pointer to its original
 450      * position. If the input stream does not support this, this method may fail
 451      * with an {@code IOException}.
 452      *
 453      * @param  stream the source of the sound bank data
 454      * @return the sound bank
 455      * @throws InvalidMidiDataException if the stream does not point to valid
 456      *         MIDI soundbank data recognized by the system
 457      * @throws IOException if an I/O error occurred when loading the soundbank
 458      * @see InputStream#markSupported
 459      * @see InputStream#mark
 460      */
 461     public static Soundbank getSoundbank(InputStream stream)
 462         throws InvalidMidiDataException, IOException {
 463 
 464         SoundbankReader sp = null;
 465         Soundbank s = null;
 466 
 467         List<SoundbankReader> providers = getSoundbankReaders();
 468 
 469         for(int i = 0; i < providers.size(); i++) {
 470             sp = providers.get(i);
 471             s = sp.getSoundbank(stream);
 472 
 473             if( s!= null) {
 474                 return s;
 475             }
 476         }
 477         throw new InvalidMidiDataException("cannot get soundbank from stream");
 478 
 479     }
 480 

 481     /**
 482      * Constructs a {@code Soundbank} by reading it from the specified URL. The
 483      * URL must point to a valid MIDI soundbank file.
 484      *
 485      * @param  url the source of the sound bank data
 486      * @return the sound bank
 487      * @throws InvalidMidiDataException if the URL does not point to valid MIDI
 488      *         soundbank data recognized by the system
 489      * @throws IOException if an I/O error occurred when loading the soundbank
 490      */
 491     public static Soundbank getSoundbank(URL url)
 492         throws InvalidMidiDataException, IOException {
 493 
 494         SoundbankReader sp = null;
 495         Soundbank s = null;
 496 
 497         List<SoundbankReader> providers = getSoundbankReaders();
 498 
 499         for(int i = 0; i < providers.size(); i++) {
 500             sp = providers.get(i);
 501             s = sp.getSoundbank(url);
 502 
 503             if( s!= null) {
 504                 return s;
 505             }
 506         }
 507         throw new InvalidMidiDataException("cannot get soundbank from stream");
 508 
 509     }
 510 

 511     /**
 512      * Constructs a {@code Soundbank} by reading it from the specified
 513      * {@code File}. The {@code File} must point to a valid MIDI soundbank file.

 514      *
 515      * @param  file the source of the sound bank data
 516      * @return the sound bank
 517      * @throws InvalidMidiDataException if the {@code File} does not point to
 518      *         valid MIDI soundbank data recognized by the system
 519      * @throws IOException if an I/O error occurred when loading the soundbank
 520      */
 521     public static Soundbank getSoundbank(File file)
 522         throws InvalidMidiDataException, IOException {
 523 
 524         SoundbankReader sp = null;
 525         Soundbank s = null;
 526 
 527         List<SoundbankReader> providers = getSoundbankReaders();
 528 
 529         for(int i = 0; i < providers.size(); i++) {
 530             sp = providers.get(i);
 531             s = sp.getSoundbank(file);
 532 
 533             if( s!= null) {
 534                 return s;
 535             }
 536         }
 537         throw new InvalidMidiDataException("cannot get soundbank from stream");
 538     }
 539 


 540     /**
 541      * Obtains the MIDI file format of the data in the specified input stream.
 542      * The stream must point to valid MIDI file data for a file type recognized
 543      * by the system.
 544      * <p>
 545      * This method and/or the code it invokes may need to read some data from
 546      * the stream to determine whether its data format is supported. The
 547      * implementation may therefore need to mark the stream, read enough data to
 548      * determine whether it is in a supported format, and reset the stream's
 549      * read pointer to its original position. If the input stream does not
 550      * permit this set of operations, this method may fail with an
 551      * {@code IOException}.
 552      * <p>
 553      * This operation can only succeed for files of a type which can be parsed
 554      * by an installed file reader. It may fail with an
 555      * {@code InvalidMidiDataException} even for valid files if no compatible
 556      * file reader is installed. It will also fail with an
 557      * {@code InvalidMidiDataException} if a compatible file reader is
 558      * installed, but encounters errors while determining the file format.
 559      *
 560      * @param  stream the input stream from which file format information should
 561      *         be extracted
 562      * @return an {@code MidiFileFormat} object describing the MIDI file format
 563      * @throws InvalidMidiDataException if the stream does not point to valid
 564      *         MIDI file data recognized by the system
 565      * @throws IOException if an I/O exception occurs while accessing the
 566      *         stream
 567      * @see #getMidiFileFormat(URL)
 568      * @see #getMidiFileFormat(File)
 569      * @see InputStream#markSupported
 570      * @see InputStream#mark
 571      */
 572     public static MidiFileFormat getMidiFileFormat(InputStream stream)
 573         throws InvalidMidiDataException, IOException {
 574 
 575         List<MidiFileReader> providers = getMidiFileReaders();
 576         MidiFileFormat format = null;
 577 
 578         for(int i = 0; i < providers.size(); i++) {
 579             MidiFileReader reader =  providers.get(i);
 580             try {
 581                 format = reader.getMidiFileFormat( stream ); // throws IOException
 582                 break;
 583             } catch (InvalidMidiDataException e) {
 584                 continue;
 585             }
 586         }
 587 
 588         if( format==null ) {
 589             throw new InvalidMidiDataException("input stream is not a supported file type");
 590         } else {
 591             return format;
 592         }
 593     }
 594 

 595     /**
 596      * Obtains the MIDI file format of the data in the specified URL. The URL
 597      * must point to valid MIDI file data for a file type recognized by the
 598      * system.
 599      * <p>
 600      * This operation can only succeed for files of a type which can be parsed
 601      * by an installed file reader. It may fail with an
 602      * {@code InvalidMidiDataException} even for valid files if no compatible
 603      * file reader is installed. It will also fail with an
 604      * {@code InvalidMidiDataException} if a compatible file reader is
 605      * installed, but encounters errors while determining the file format.
 606      *
 607      * @param  url the URL from which file format information should be
 608      *         extracted
 609      * @return a {@code MidiFileFormat} object describing the MIDI file format

 610      * @throws InvalidMidiDataException if the URL does not point to valid MIDI
 611      *         file data recognized by the system
 612      * @throws IOException if an I/O exception occurs while accessing the URL

 613      * @see #getMidiFileFormat(InputStream)
 614      * @see #getMidiFileFormat(File)
 615      */
 616     public static MidiFileFormat getMidiFileFormat(URL url)
 617         throws InvalidMidiDataException, IOException {
 618 
 619         List<MidiFileReader> providers = getMidiFileReaders();
 620         MidiFileFormat format = null;
 621 
 622         for(int i = 0; i < providers.size(); i++) {
 623             MidiFileReader reader = providers.get(i);
 624             try {
 625                 format = reader.getMidiFileFormat( url ); // throws IOException
 626                 break;
 627             } catch (InvalidMidiDataException e) {
 628                 continue;
 629             }
 630         }
 631 
 632         if( format==null ) {
 633             throw new InvalidMidiDataException("url is not a supported file type");
 634         } else {
 635             return format;
 636         }
 637     }
 638 

 639     /**
 640      * Obtains the MIDI file format of the specified {@code File}. The
 641      * {@code File} must point to valid MIDI file data for a file type
 642      * recognized by the system.
 643      * <p>
 644      * This operation can only succeed for files of a type which can be parsed
 645      * by an installed file reader. It may fail with an
 646      * {@code InvalidMidiDataException} even for valid files if no compatible
 647      * file reader is installed. It will also fail with an
 648      * {@code InvalidMidiDataException} if a compatible file reader is
 649      * installed, but encounters errors while determining the file format.
 650      *
 651      * @param  file the {@code File} from which file format information should
 652      *         be extracted
 653      * @return a {@code MidiFileFormat} object describing the MIDI file format
 654      * @throws InvalidMidiDataException if the {@code File} does not point to
 655      *         valid MIDI file data recognized by the system
 656      * @throws IOException if an I/O exception occurs while accessing the file

 657      * @see #getMidiFileFormat(InputStream)
 658      * @see #getMidiFileFormat(URL)
 659      */
 660     public static MidiFileFormat getMidiFileFormat(File file)
 661         throws InvalidMidiDataException, IOException {
 662 
 663         List<MidiFileReader> providers = getMidiFileReaders();
 664         MidiFileFormat format = null;
 665 
 666         for(int i = 0; i < providers.size(); i++) {
 667             MidiFileReader reader = providers.get(i);
 668             try {
 669                 format = reader.getMidiFileFormat( file ); // throws IOException
 670                 break;
 671             } catch (InvalidMidiDataException e) {
 672                 continue;
 673             }
 674         }
 675 
 676         if( format==null ) {
 677             throw new InvalidMidiDataException("file is not a supported file type");
 678         } else {
 679             return format;
 680         }
 681     }
 682 

 683     /**
 684      * Obtains a MIDI sequence from the specified input stream. The stream must
 685      * point to valid MIDI file data for a file type recognized by the system.

 686      * <p>
 687      * This method and/or the code it invokes may need to read some data from
 688      * the stream to determine whether its data format is supported. The
 689      * implementation may therefore need to mark the stream, read enough data to
 690      * determine whether it is in a supported format, and reset the stream's
 691      * read pointer to its original position. If the input stream does not
 692      * permit this set of operations, this method may fail with an
 693      * {@code IOException}.
 694      * <p>
 695      * This operation can only succeed for files of a type which can be parsed
 696      * by an installed file reader. It may fail with an
 697      * {@code InvalidMidiDataException} even for valid files if no compatible
 698      * file reader is installed. It will also fail with an
 699      * {@code InvalidMidiDataException} if a compatible file reader is
 700      * installed, but encounters errors while constructing the {@code Sequence}
 701      * object from the file data.
 702      *
 703      * @param  stream the input stream from which the {@code Sequence} should be
 704      *         constructed
 705      * @return a {@code Sequence} object based on the MIDI file data contained
 706      *         in the input stream
 707      * @throws InvalidMidiDataException if the stream does not point to valid
 708      *         MIDI file data recognized by the system
 709      * @throws IOException if an I/O exception occurs while accessing the stream

 710      * @see InputStream#markSupported
 711      * @see InputStream#mark
 712      */
 713     public static Sequence getSequence(InputStream stream)
 714         throws InvalidMidiDataException, IOException {
 715 
 716         List<MidiFileReader> providers = getMidiFileReaders();
 717         Sequence sequence = null;
 718 
 719         for(int i = 0; i < providers.size(); i++) {
 720             MidiFileReader reader = providers.get(i);
 721             try {
 722                 sequence = reader.getSequence( stream ); // throws IOException
 723                 break;
 724             } catch (InvalidMidiDataException e) {
 725                 continue;
 726             }
 727         }
 728 
 729         if( sequence==null ) {
 730             throw new InvalidMidiDataException("could not get sequence from input stream");
 731         } else {
 732             return sequence;
 733         }
 734     }
 735 

 736     /**
 737      * Obtains a MIDI sequence from the specified URL. The URL must point to
 738      * valid MIDI file data for a file type recognized by the system.

 739      * <p>
 740      * This operation can only succeed for files of a type which can be parsed
 741      * by an installed file reader. It may fail with an
 742      * {@code InvalidMidiDataException} even for valid files if no compatible
 743      * file reader is installed. It will also fail with an
 744      * {@code InvalidMidiDataException} if a compatible file reader is
 745      * installed, but encounters errors while constructing the {@code Sequence}
 746      * object from the file data.
 747      *
 748      * @param  url the URL from which the {@code Sequence} should be constructed
 749      * @return a {@code Sequence} object based on the MIDI file data pointed to
 750      *         by the URL

 751      * @throws InvalidMidiDataException if the URL does not point to valid MIDI
 752      *         file data recognized by the system
 753      * @throws IOException if an I/O exception occurs while accessing the URL
 754      */
 755     public static Sequence getSequence(URL url)
 756         throws InvalidMidiDataException, IOException {
 757 
 758         List<MidiFileReader> providers = getMidiFileReaders();
 759         Sequence sequence = null;
 760 
 761         for(int i = 0; i < providers.size(); i++) {
 762             MidiFileReader reader = providers.get(i);
 763             try {
 764                 sequence = reader.getSequence( url ); // throws IOException
 765                 break;
 766             } catch (InvalidMidiDataException e) {
 767                 continue;
 768             }
 769         }
 770 
 771         if( sequence==null ) {
 772             throw new InvalidMidiDataException("could not get sequence from URL");
 773         } else {
 774             return sequence;
 775         }
 776     }
 777 

 778     /**
 779      * Obtains a MIDI sequence from the specified {@code File}. The {@code File}
 780      * must point to valid MIDI file data for a file type recognized by the
 781      * system.
 782      * <p>
 783      * This operation can only succeed for files of a type which can be parsed
 784      * by an installed file reader. It may fail with an
 785      * {@code InvalidMidiDataException} even for valid files if no compatible
 786      * file reader is installed. It will also fail with an
 787      * {@code InvalidMidiDataException} if a compatible file reader is
 788      * installed, but encounters errors while constructing the {@code Sequence}
 789      * object from the file data.
 790      *
 791      * @param  file the {@code File} from which the {@code Sequence} should be
 792      *         constructed
 793      * @return a {@code Sequence} object based on the MIDI file data pointed to
 794      *         by the File
 795      * @throws InvalidMidiDataException if the File does not point to valid MIDI
 796      *         file data recognized by the system
 797      * @throws IOException if an I/O exception occurs
 798      */
 799     public static Sequence getSequence(File file)
 800         throws InvalidMidiDataException, IOException {
 801 
 802         List<MidiFileReader> providers = getMidiFileReaders();
 803         Sequence sequence = null;
 804 
 805         for(int i = 0; i < providers.size(); i++) {
 806             MidiFileReader reader = providers.get(i);
 807             try {
 808                 sequence = reader.getSequence( file ); // throws IOException
 809                 break;
 810             } catch (InvalidMidiDataException e) {
 811                 continue;
 812             }
 813         }
 814 
 815         if( sequence==null ) {
 816             throw new InvalidMidiDataException("could not get sequence from file");
 817         } else {
 818             return sequence;
 819         }
 820     }
 821 

 822     /**
 823      * Obtains the set of MIDI file types for which file writing support is
 824      * provided by the system.
 825      *
 826      * @return array of unique file types. If no file types are supported, an
 827      *         array of length 0 is returned.
 828      */
 829     public static int[] getMidiFileTypes() {
 830 
 831         List<MidiFileWriter> providers = getMidiFileWriters();
 832         Set<Integer> allTypes = new HashSet<>();
 833 
 834         // gather from all the providers
 835 
 836         for (int i = 0; i < providers.size(); i++ ) {
 837             MidiFileWriter writer = providers.get(i);
 838             int[] types = writer.getMidiFileTypes();
 839             for (int j = 0; j < types.length; j++ ) {
 840                 allTypes.add(types[j]);
 841             }
 842         }
 843         int resultTypes[] = new int[allTypes.size()];
 844         int index = 0;
 845         Iterator<Integer> iterator = allTypes.iterator();
 846         while (iterator.hasNext()) {
 847             Integer integer = iterator.next();
 848             resultTypes[index++] = integer.intValue();
 849         }
 850         return resultTypes;
 851     }
 852 

 853     /**
 854      * Indicates whether file writing support for the specified MIDI file type
 855      * is provided by the system.
 856      *
 857      * @param  fileType the file type for which write capabilities are queried
 858      * @return {@code true} if the file type is supported, otherwise
 859      *         {@code false}
 860      */
 861     public static boolean isFileTypeSupported(int fileType) {
 862 
 863         List<MidiFileWriter> providers = getMidiFileWriters();
 864 
 865         for (int i = 0; i < providers.size(); i++ ) {
 866             MidiFileWriter writer = providers.get(i);
 867             if( writer.isFileTypeSupported(fileType)) {
 868                 return true;
 869             }
 870         }
 871         return false;
 872     }
 873 

 874     /**
 875      * Obtains the set of MIDI file types that the system can write from the
 876      * sequence specified.
 877      *
 878      * @param  sequence the sequence for which MIDI file type support is queried
 879      * @return the set of unique supported file types. If no file types are
 880      *         supported, returns an array of length 0.
 881      */
 882     public static int[] getMidiFileTypes(Sequence sequence) {
 883 
 884         List<MidiFileWriter> providers = getMidiFileWriters();
 885         Set<Integer> allTypes = new HashSet<>();
 886 
 887         // gather from all the providers
 888 
 889         for (int i = 0; i < providers.size(); i++ ) {
 890             MidiFileWriter writer = providers.get(i);
 891             int[] types = writer.getMidiFileTypes(sequence);
 892             for (int j = 0; j < types.length; j++ ) {
 893                 allTypes.add(types[j]);
 894             }
 895         }
 896         int resultTypes[] = new int[allTypes.size()];
 897         int index = 0;
 898         Iterator<Integer> iterator = allTypes.iterator();
 899         while (iterator.hasNext()) {
 900             Integer integer = iterator.next();
 901             resultTypes[index++] = integer.intValue();
 902         }
 903         return resultTypes;
 904     }
 905 

 906     /**
 907      * Indicates whether a MIDI file of the file type specified can be written
 908      * from the sequence indicated.
 909      *
 910      * @param  fileType the file type for which write capabilities are queried
 911      * @param  sequence the sequence for which file writing support is queried
 912      * @return {@code true} if the file type is supported for this sequence,
 913      *         otherwise {@code false}
 914      */
 915     public static boolean isFileTypeSupported(int fileType, Sequence sequence) {
 916 
 917         List<MidiFileWriter> providers = getMidiFileWriters();
 918 
 919         for (int i = 0; i < providers.size(); i++ ) {
 920             MidiFileWriter writer = providers.get(i);
 921             if( writer.isFileTypeSupported(fileType,sequence)) {
 922                 return true;
 923             }
 924         }
 925         return false;
 926     }
 927 

 928     /**
 929      * Writes a stream of bytes representing a file of the MIDI file type
 930      * indicated to the output stream provided.
 931      *
 932      * @param  in sequence containing MIDI data to be written to the file
 933      * @param  fileType the file type of the file to be written to the output
 934      *         stream
 935      * @param  out stream to which the file data should be written
 936      * @return the number of bytes written to the output stream
 937      * @throws IOException if an I/O exception occurs
 938      * @throws IllegalArgumentException if the file format is not supported by
 939      *         the system
 940      * @see #isFileTypeSupported(int, Sequence)
 941      * @see #getMidiFileTypes(Sequence)
 942      */
 943     public static int write(Sequence in, int fileType, OutputStream out) throws IOException {
 944 
 945         List<MidiFileWriter> providers = getMidiFileWriters();
 946         //$$fb 2002-04-17: Fix for 4635287: Standard MidiFileWriter cannot write empty Sequences
 947         int bytesWritten = -2;
 948 
 949         for (int i = 0; i < providers.size(); i++ ) {
 950             MidiFileWriter writer = providers.get(i);
 951             if( writer.isFileTypeSupported( fileType, in ) ) {
 952 
 953                 bytesWritten = writer.write(in, fileType, out);
 954                 break;
 955             }
 956         }
 957         if (bytesWritten == -2) {
 958             throw new IllegalArgumentException("MIDI file type is not supported");
 959         }
 960         return bytesWritten;
 961     }
 962 

 963     /**
 964      * Writes a stream of bytes representing a file of the MIDI file type
 965      * indicated to the external file provided.
 966      *
 967      * @param  in sequence containing MIDI data to be written to the file
 968      * @param  type the file type of the file to be written to the output stream
 969      * @param  out external file to which the file data should be written
 970      * @return the number of bytes written to the file
 971      * @throws IOException if an I/O exception occurs
 972      * @throws IllegalArgumentException if the file type is not supported by the
 973      *         system
 974      * @see #isFileTypeSupported(int, Sequence)
 975      * @see #getMidiFileTypes(Sequence)
 976      */
 977     public static int write(Sequence in, int type, File out) throws IOException {
 978 
 979         List<MidiFileWriter> providers = getMidiFileWriters();
 980         //$$fb 2002-04-17: Fix for 4635287: Standard MidiFileWriter cannot write empty Sequences
 981         int bytesWritten = -2;
 982 
 983         for (int i = 0; i < providers.size(); i++ ) {
 984             MidiFileWriter writer = providers.get(i);
 985             if( writer.isFileTypeSupported( type, in ) ) {
 986 
 987                 bytesWritten = writer.write(in, type, out);
 988                 break;
 989             }
 990         }
 991         if (bytesWritten == -2) {
 992             throw new IllegalArgumentException("MIDI file type is not supported");
 993         }
 994         return bytesWritten;
 995     }
 996 


 997     // HELPER METHODS
 998     @SuppressWarnings("unchecked")
 999     private static List<MidiDeviceProvider> getMidiDeviceProviders() {
1000         return (List<MidiDeviceProvider>) getProviders(MidiDeviceProvider.class);
1001     }
1002 
1003     @SuppressWarnings("unchecked")
1004     private static List<SoundbankReader> getSoundbankReaders() {
1005         return (List<SoundbankReader>) getProviders(SoundbankReader.class);
1006     }
1007 
1008     @SuppressWarnings("unchecked")
1009     private static List<MidiFileWriter> getMidiFileWriters() {
1010         return (List<MidiFileWriter>) getProviders(MidiFileWriter.class);
1011     }
1012 
1013     @SuppressWarnings("unchecked")
1014     private static List<MidiFileReader> getMidiFileReaders() {
1015         return (List<MidiFileReader>) getProviders(MidiFileReader.class);
1016     }
1017 
1018     /**
1019      * Attempts to locate and return a default MidiDevice of the specified type.


1020      * This method wraps {@link #getDefaultDevice}. It catches the
1021      * {@code IllegalArgumentException} thrown by {@code getDefaultDevice} and
1022      * instead throws a {@code MidiUnavailableException}, with the catched

1023      * exception chained.
1024      *
1025      * @param  deviceClass The requested device type, one of Synthesizer.class,
1026      *         Sequencer.class, Receiver.class or Transmitter.class
1027      * @throws MidiUnavailableException on failure
1028      */
1029     private static MidiDevice getDefaultDeviceWrapper(Class<?> deviceClass)
1030         throws MidiUnavailableException{
1031         try {
1032             return getDefaultDevice(deviceClass);
1033         } catch (IllegalArgumentException iae) {
1034             MidiUnavailableException mae = new MidiUnavailableException();
1035             mae.initCause(iae);
1036             throw mae;
1037         }
1038     }
1039 
1040     /**
1041      * Attempts to locate and return a default MidiDevice of the specified type.

1042      *
1043      * @param  deviceClass The requested device type, one of Synthesizer.class,
1044      *         Sequencer.class, Receiver.class or Transmitter.class
1045      * @throws IllegalArgumentException on failure
1046      */
1047     private static MidiDevice getDefaultDevice(Class<?> deviceClass) {
1048         List<MidiDeviceProvider> providers = getMidiDeviceProviders();
1049         String providerClassName = JDK13Services.getDefaultProviderClassName(deviceClass);
1050         String instanceName = JDK13Services.getDefaultInstanceName(deviceClass);
1051         MidiDevice device;
1052 
1053         if (providerClassName != null) {
1054             MidiDeviceProvider defaultProvider = getNamedProvider(providerClassName, providers);
1055             if (defaultProvider != null) {
1056                 if (instanceName != null) {
1057                     device = getNamedDevice(instanceName, defaultProvider, deviceClass);
1058                     if (device != null) {
1059                         return device;
1060                     }
1061                 }
1062                 device = getFirstDevice(defaultProvider, deviceClass);
1063                 if (device != null) {
1064                     return device;
1065                 }
1066             }
1067         }
1068 
1069         /* Provider class not specified or cannot be found, or
1070            provider class specified, and no appropriate device available or
1071            provider class and instance specified and instance cannot be found or is not appropriate */
1072         if (instanceName != null) {
1073             device = getNamedDevice(instanceName, providers, deviceClass);
1074             if (device != null) {
1075                 return device;
1076             }
1077         }
1078 
1079         /* No default are specified, or if something is specified, everything
1080            failed. */
1081         device = getFirstDevice(providers, deviceClass);
1082         if (device != null) {
1083             return device;
1084         }
1085         throw new IllegalArgumentException("Requested device not installed");
1086     }
1087 
1088     /**
1089      * Return a MidiDeviceProvider of a given class from the list of
1090      * MidiDeviceProviders.
1091      *
1092      * @param  providerClassName The class name of the provider to be returned
1093      * @param  providers The list of MidiDeviceProviders that is searched
1094      * @return A MidiDeviceProvider of the requested class, or null if none is
1095      *         found

1096      */
1097     private static MidiDeviceProvider getNamedProvider(String providerClassName,
1098                                                        List<MidiDeviceProvider> providers) {
1099         for(int i = 0; i < providers.size(); i++) {
1100             MidiDeviceProvider provider = providers.get(i);
1101             if (provider.getClass().getName().equals(providerClassName)) {
1102                 return provider;
1103             }
1104         }
1105         return null;
1106     }
1107 
1108     /**
1109      * Return a MidiDevice with a given name from a given MidiDeviceProvider.
1110      *
1111      * @param  deviceName The name of the MidiDevice to be returned
1112      * @param  provider The MidiDeviceProvider to check for MidiDevices
1113      * @param  deviceClass The requested device type, one of Synthesizer.class,
1114      *         Sequencer.class, Receiver.class or Transmitter.class
1115      * @return A MidiDevice matching the requirements, or null if none is found
1116      */
1117     private static MidiDevice getNamedDevice(String deviceName,
1118                                              MidiDeviceProvider provider,
1119                                              Class<?> deviceClass) {
1120         MidiDevice device;
1121         // try to get MIDI port
1122         device = getNamedDevice(deviceName, provider, deviceClass,
1123                                  false, false);
1124         if (device != null) {
1125             return device;
1126         }
1127 
1128         if (deviceClass == Receiver.class) {
1129             // try to get Synthesizer
1130             device = getNamedDevice(deviceName, provider, deviceClass,
1131                                      true, false);
1132             if (device != null) {
1133                 return device;
1134             }
1135         }
1136 
1137         return null;
1138     }
1139 
1140     /**
1141      * Return a MidiDevice with a given name from a given MidiDeviceProvider.
1142      *
1143      * @param  deviceName The name of the MidiDevice to be returned
1144      * @param  provider The MidiDeviceProvider to check for MidiDevices
1145      * @param  deviceClass The requested device type, one of Synthesizer.class,
1146      *         Sequencer.class, Receiver.class or Transmitter.class
1147      * @return A MidiDevice matching the requirements, or null if none is found
1148      */
1149     private static MidiDevice getNamedDevice(String deviceName,
1150                                              MidiDeviceProvider provider,
1151                                              Class<?> deviceClass,
1152                                              boolean allowSynthesizer,
1153                                              boolean allowSequencer) {
1154         MidiDevice.Info[] infos = provider.getDeviceInfo();
1155         for (int i = 0; i < infos.length; i++) {
1156             if (infos[i].getName().equals(deviceName)) {
1157                 MidiDevice device = provider.getDevice(infos[i]);
1158                 if (isAppropriateDevice(device, deviceClass,
1159                                         allowSynthesizer, allowSequencer)) {
1160                     return device;
1161                 }
1162             }
1163         }
1164         return null;
1165     }
1166 
1167     /**
1168      * Return a MidiDevice with a given name from a list of MidiDeviceProviders.
1169      *
1170      * @param  deviceName The name of the MidiDevice to be returned
1171      * @param  providers The List of MidiDeviceProviders to check for
1172      *         MidiDevices
1173      * @param  deviceClass The requested device type, one of Synthesizer.class,
1174      *         Sequencer.class, Receiver.class or Transmitter.class
1175      * @return A Mixer matching the requirements, or null if none is found
1176      */
1177     private static MidiDevice getNamedDevice(String deviceName,
1178                                              List<MidiDeviceProvider> providers,
1179                                              Class<?> deviceClass) {
1180         MidiDevice device;
1181         // try to get MIDI port
1182         device = getNamedDevice(deviceName, providers, deviceClass,
1183                                  false, false);
1184         if (device != null) {
1185             return device;
1186         }
1187 
1188         if (deviceClass == Receiver.class) {
1189             // try to get Synthesizer
1190             device = getNamedDevice(deviceName, providers, deviceClass,
1191                                      true, false);
1192             if (device != null) {
1193                 return device;
1194             }
1195         }
1196 
1197         return null;
1198     }
1199 
1200     /**
1201      * Return a MidiDevice with a given name from a list of MidiDeviceProviders.
1202      *
1203      * @param  deviceName The name of the MidiDevice to be returned
1204      * @param  providers The List of MidiDeviceProviders to check for
1205      *         MidiDevices
1206      * @param  deviceClass The requested device type, one of Synthesizer.class,
1207      *         Sequencer.class, Receiver.class or Transmitter.class
1208      * @return A Mixer matching the requirements, or null if none is found
1209      */
1210     private static MidiDevice getNamedDevice(String deviceName,
1211                                              List<MidiDeviceProvider> providers,
1212                                              Class<?> deviceClass,
1213                                              boolean allowSynthesizer,
1214                                              boolean allowSequencer) {
1215         for(int i = 0; i < providers.size(); i++) {
1216             MidiDeviceProvider provider = providers.get(i);
1217             MidiDevice device = getNamedDevice(deviceName, provider,
1218                                                deviceClass,
1219                                                allowSynthesizer,
1220                                                allowSequencer);
1221             if (device != null) {
1222                 return device;
1223             }
1224         }
1225         return null;
1226     }
1227 
1228     /**
1229      * From a given MidiDeviceProvider, return the first appropriate device.
1230      *
1231      * @param  provider The MidiDeviceProvider to check for MidiDevices
1232      * @param  deviceClass The requested device type, one of Synthesizer.class,
1233      *         Sequencer.class, Receiver.class or Transmitter.class
1234      * @return A MidiDevice is considered appropriate, or null if no appropriate
1235      *         device is found
1236      */
1237     private static MidiDevice getFirstDevice(MidiDeviceProvider provider,
1238                                              Class<?> deviceClass) {
1239         MidiDevice device;
1240         // try to get MIDI port
1241         device = getFirstDevice(provider, deviceClass,
1242                                 false, false);
1243         if (device != null) {
1244             return device;
1245         }
1246 
1247         if (deviceClass == Receiver.class) {
1248             // try to get Synthesizer
1249             device = getFirstDevice(provider, deviceClass,
1250                                     true, false);
1251             if (device != null) {
1252                 return device;
1253             }
1254         }
1255 
1256         return null;
1257     }
1258 
1259     /**
1260      * From a given MidiDeviceProvider, return the first appropriate device.
1261      *
1262      * @param  provider The MidiDeviceProvider to check for MidiDevices
1263      * @param  deviceClass The requested device type, one of Synthesizer.class,
1264      *         Sequencer.class, Receiver.class or Transmitter.class
1265      * @return A MidiDevice is considered appropriate, or null if no appropriate
1266      *         device is found
1267      */
1268     private static MidiDevice getFirstDevice(MidiDeviceProvider provider,
1269                                              Class<?> deviceClass,
1270                                              boolean allowSynthesizer,
1271                                              boolean allowSequencer) {
1272         MidiDevice.Info[] infos = provider.getDeviceInfo();
1273         for (int j = 0; j < infos.length; j++) {
1274             MidiDevice device = provider.getDevice(infos[j]);
1275             if (isAppropriateDevice(device, deviceClass,
1276                                     allowSynthesizer, allowSequencer)) {
1277                 return device;
1278             }
1279         }
1280         return null;
1281     }
1282 
1283     /**
1284      * From a List of MidiDeviceProviders, return the first appropriate
1285      * MidiDevice.
1286      *
1287      * @param  providers The List of MidiDeviceProviders to search
1288      * @param  deviceClass The requested device type, one of Synthesizer.class,
1289      *         Sequencer.class, Receiver.class or Transmitter.class
1290      * @return A MidiDevice that is considered appropriate, or null if none is
1291      *         found
1292      */
1293     private static MidiDevice getFirstDevice(List<MidiDeviceProvider> providers,
1294                                              Class<?> deviceClass) {
1295         MidiDevice device;
1296         // try to get MIDI port
1297         device = getFirstDevice(providers, deviceClass,
1298                                 false, false);
1299         if (device != null) {
1300             return device;
1301         }
1302 
1303         if (deviceClass == Receiver.class) {
1304             // try to get Synthesizer
1305             device = getFirstDevice(providers, deviceClass,
1306                                     true, false);
1307             if (device != null) {
1308                 return device;
1309             }
1310         }
1311 
1312         return null;
1313     }
1314 
1315     /**
1316      * From a List of MidiDeviceProviders, return the first appropriate
1317      * MidiDevice.
1318      *
1319      * @param  providers The List of MidiDeviceProviders to search
1320      * @param  deviceClass The requested device type, one of Synthesizer.class,
1321      *         Sequencer.class, Receiver.class or Transmitter.class
1322      * @return A MidiDevice that is considered appropriate, or null if none is
1323      *         found
1324      */
1325     private static MidiDevice getFirstDevice(List<MidiDeviceProvider> providers,
1326                                              Class<?> deviceClass,
1327                                              boolean allowSynthesizer,
1328                                              boolean allowSequencer) {
1329         for(int i = 0; i < providers.size(); i++) {
1330             MidiDeviceProvider provider = providers.get(i);
1331             MidiDevice device = getFirstDevice(provider, deviceClass,
1332                                                allowSynthesizer,
1333                                                allowSequencer);
1334             if (device != null) {
1335                 return device;
1336             }
1337         }
1338         return null;
1339     }
1340 
1341     /**
1342      * Checks if a MidiDevice is appropriate. If deviceClass is Synthesizer or
1343      * Sequencer, a device implementing the respective interface is considered
1344      * appropriate. If deviceClass is Receiver or Transmitter, a device is
1345      * considered appropriate if it implements neither Synthesizer nor
1346      * Transmitter, and if it can provide at least one Receiver or Transmitter,
1347      * respectively.
1348      *
1349      * @param  device the MidiDevice to test
1350      * @param  allowSynthesizer if true, Synthesizers are considered
1351      *         appropriate. Otherwise only pure MidiDevices are considered
1352      *         appropriate (unless allowSequencer is true). This flag only has
1353      *         an effect for deviceClass Receiver and Transmitter. For other
1354      *         device classes (Sequencer and Synthesizer), this flag has no
1355      *         effect.
1356      * @param  allowSequencer if true, Sequencers are considered appropriate.
1357      *         Otherwise only pure MidiDevices are considered appropriate
1358      *         (unless allowSynthesizer is true). This flag only has an effect
1359      *         for deviceClass Receiver and Transmitter. For other device
1360      *         classes (Sequencer and Synthesizer), this flag has no effect.
1361      * @return true if the device is considered appropriate according to the
1362      *         rules given above, false otherwise
1363      */
1364     private static boolean isAppropriateDevice(MidiDevice device,
1365                                                Class<?> deviceClass,
1366                                                boolean allowSynthesizer,
1367                                                boolean allowSequencer) {
1368         if (deviceClass.isInstance(device)) {
1369            // This clause is for deviceClass being either Synthesizer
1370             // or Sequencer.
1371             return true;
1372         } else {
1373             // Now the case that deviceClass is Transmitter or
1374             // Receiver. If neither allowSynthesizer nor allowSequencer is
1375             // true, we require device instances to be
1376             // neither Synthesizer nor Sequencer, since we only want
1377             // devices representing MIDI ports.
1378             // Otherwise, the respective type is accepted, too
1379             if ( (! (device instanceof Sequencer) &&
1380                   ! (device instanceof Synthesizer) ) ||
1381                  ((device instanceof Sequencer) && allowSequencer) ||
1382                  ((device instanceof Synthesizer) && allowSynthesizer)) {
1383                 // And of cource, the device has to be able to provide
1384                 // Receivers or Transmitters.
1385                 if ((deviceClass == Receiver.class &&
1386                      device.getMaxReceivers() != 0) ||
1387                     (deviceClass == Transmitter.class &&
1388                      device.getMaxTransmitters() != 0)) {
1389                     return true;
1390                 }
1391             }
1392         }
1393         return false;
1394     }
1395 

1396     /**
1397      * Obtains the set of services currently installed on the system using the
1398      * SPI mechanism in 1.3.
1399      *
1400      * @return a List of instances of providers for the requested service. If no
1401      *         providers are available, a List of length 0 will be returned.
1402      */
1403      private static List<?> getProviders(Class<?> providerClass) {
1404          return JDK13Services.getProviders(providerClass);
1405     }
1406 }
--- EOF ---