1 /*
   2  * Copyright (c) 1999, 2017, 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.sampled;
  27 
  28 import java.io.EOFException;
  29 import java.io.File;
  30 import java.io.IOException;
  31 import java.io.InputStream;
  32 import java.io.OutputStream;
  33 import java.net.URL;
  34 import java.util.ArrayList;
  35 import java.util.Collections;
  36 import java.util.HashSet;
  37 import java.util.List;
  38 import java.util.Objects;
  39 import java.util.Properties;
  40 import java.util.Set;
  41 import java.util.Vector;
  42 
  43 import javax.sound.sampled.spi.AudioFileReader;
  44 import javax.sound.sampled.spi.AudioFileWriter;
  45 import javax.sound.sampled.spi.FormatConversionProvider;
  46 import javax.sound.sampled.spi.MixerProvider;
  47 
  48 import com.sun.media.sound.JDK13Services;
  49 
  50 /* $fb TODO:
  51  * - consistent usage of (typed) collections
  52  */
  53 
  54 
  55 /**
  56  * The {@code AudioSystem} class acts as the entry point to the sampled-audio
  57  * system resources. This class lets you query and access the mixers that are
  58  * installed on the system. {@code AudioSystem} includes a number of methods for
  59  * converting audio data between different formats, and for translating between
  60  * audio files and streams. It also provides a method for obtaining a
  61  * {@link Line} directly from the {@code AudioSystem} without dealing explicitly
  62  * with mixers.
  63  * <p>
  64  * Properties can be used to specify the default mixer for specific line types.
  65  * Both system properties and a properties file are considered. The
  66  * "sound.properties" properties file is read from an implementation-specific
  67  * location (typically it is the {@code conf} directory in the Java installation
  68  * directory). If a property exists both as a system property and in the
  69  * properties file, the system property takes precedence. If none is specified,
  70  * a suitable default is chosen among the available devices. The syntax of the
  71  * properties file is specified in
  72  * {@link Properties#load(InputStream) Properties.load}. The following table
  73  * lists the available property keys and which methods consider them:
  74  *
  75  * <table class="striped">
  76  * <caption>Audio System Property Keys</caption>
  77  * <thead>
  78  *  <tr>
  79  *   <th>Property Key</th>
  80  *   <th>Interface</th>
  81  *   <th>Affected Method(s)</th>
  82  *  </tr>
  83  * </thead>
  84  * <tbody>
  85  *  <tr>
  86  *   <td>{@code javax.sound.sampled.Clip}</td>
  87  *   <td>{@link Clip}</td>
  88  *   <td>{@link #getLine}, {@link #getClip}</td>
  89  *  </tr>
  90  *  <tr>
  91  *   <td>{@code javax.sound.sampled.Port}</td>
  92  *   <td>{@link Port}</td>
  93  *   <td>{@link #getLine}</td>
  94  *  </tr>
  95  *  <tr>
  96  *   <td>{@code javax.sound.sampled.SourceDataLine}</td>
  97  *   <td>{@link SourceDataLine}</td>
  98  *   <td>{@link #getLine}, {@link #getSourceDataLine}</td>
  99  *  </tr>
 100  *  <tr>
 101  *   <td>{@code javax.sound.sampled.TargetDataLine}</td>
 102  *   <td>{@link TargetDataLine}</td>
 103  *   <td>{@link #getLine}, {@link #getTargetDataLine}</td>
 104  *  </tr>
 105  * </tbody>
 106  * </table>
 107  *
 108  * The property value consists of the provider class name and the mixer name,
 109  * separated by the hash mark (&quot;#&quot;). The provider class name is the
 110  * fully-qualified name of a concrete {@link MixerProvider mixer provider}
 111  * class. The mixer name is matched against the {@code String} returned by the
 112  * {@code getName} method of {@code Mixer.Info}. Either the class name, or the
 113  * mixer name may be omitted. If only the class name is specified, the trailing
 114  * hash mark is optional.
 115  * <p>
 116  * If the provider class is specified, and it can be successfully retrieved from
 117  * the installed providers, the list of {@code Mixer.Info} objects is retrieved
 118  * from the provider. Otherwise, or when these mixers do not provide a
 119  * subsequent match, the list is retrieved from {@link #getMixerInfo} to contain
 120  * all available {@code Mixer.Info} objects.
 121  * <p>
 122  * If a mixer name is specified, the resulting list of {@code Mixer.Info}
 123  * objects is searched: the first one with a matching name, and whose
 124  * {@code Mixer} provides the respective line interface, will be returned. If no
 125  * matching {@code Mixer.Info} object is found, or the mixer name is not
 126  * specified, the first mixer from the resulting list, which provides the
 127  * respective line interface, will be returned.
 128  *
 129  * For example, the property {@code javax.sound.sampled.Clip} with a value
 130  * {@code "com.sun.media.sound.MixerProvider#SunClip"}
 131  * will have the following consequences when {@code getLine} is called
 132  * requesting a {@code Clip} instance: if the class
 133  * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
 134  * mixer providers, the first {@code Clip} from the first mixer with name
 135  * {@code "SunClip"} will be returned. If it cannot be found, the
 136  * first {@code Clip} from the first mixer of the specified provider will be
 137  * returned, regardless of name. If there is none, the first {@code Clip} from
 138  * the first {@code Mixer} with name {@code "SunClip"} in the list of
 139  * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not
 140  * found, the first {@code Clip} of the first {@code Mixer} that can be found in
 141  * the list of all mixers is returned. If that fails, too, an
 142  * {@code IllegalArgumentException} is thrown.
 143  *
 144  * @author Kara Kytle
 145  * @author Florian Bomers
 146  * @author Matthias Pfisterer
 147  * @author Kevin P. Smith
 148  * @see AudioFormat
 149  * @see AudioInputStream
 150  * @see Mixer
 151  * @see Line
 152  * @see Line.Info
 153  * @since 1.3
 154  */
 155 public class AudioSystem {
 156 
 157     /**
 158      * An integer that stands for an unknown numeric value. This value is
 159      * appropriate only for signed quantities that do not normally take negative
 160      * values. Examples include file sizes, frame sizes, buffer sizes, and
 161      * sample rates. A number of Java Sound constructors accept a value of
 162      * {@code NOT_SPECIFIED} for such parameters. Other methods may also accept
 163      * or return this value, as documented.
 164      */
 165     public static final int NOT_SPECIFIED = -1;
 166 
 167     /**
 168      * Private no-args constructor for ensuring against instantiation.
 169      */
 170     private AudioSystem() {
 171     }
 172 
 173     /**
 174      * Obtains an array of mixer info objects that represents the set of audio
 175      * mixers that are currently installed on the system.
 176      *
 177      * @return an array of info objects for the currently installed mixers. If
 178      *         no mixers are available on the system, an array of length 0 is
 179      *         returned.
 180      * @see #getMixer
 181      */
 182     public static Mixer.Info[] getMixerInfo() {
 183 
 184         List<Mixer.Info> infos = getMixerInfoList();
 185         Mixer.Info[] allInfos = infos.toArray(new Mixer.Info[infos.size()]);
 186         return allInfos;
 187     }
 188 
 189     /**
 190      * Obtains the requested audio mixer.
 191      *
 192      * @param  info a {@code Mixer.Info} object representing the desired mixer,
 193      *         or {@code null} for the system default mixer
 194      * @return the requested mixer
 195      * @throws SecurityException if the requested mixer is unavailable because
 196      *         of security restrictions
 197      * @throws IllegalArgumentException if the info object does not represent a
 198      *         mixer installed on the system
 199      * @see #getMixerInfo
 200      */
 201     public static Mixer getMixer(final Mixer.Info info) {
 202         for (final MixerProvider provider : getMixerProviders()) {
 203             try {
 204                 return provider.getMixer(info);
 205             } catch (IllegalArgumentException | NullPointerException ignored) {
 206                 // The MixerProvider.getMixer(null) should return default Mixer,
 207                 // This behaviour was assumed from the beginning, but strictly
 208                 // specified only in the jdk9. Since the jdk1.1.5 we skipped
 209                 // NPE for some reason and therefore skipped some
 210                 // implementations of MixerProviders, which throw NPE. To keep
 211                 // support of such implementations, we still ignore NPE.
 212             }
 213         }
 214         throw new IllegalArgumentException(
 215                 String.format("Mixer not supported: %s", info));
 216     }
 217 
 218     //$$fb 2002-11-26: fix for 4757930: DOC: AudioSystem.getTarget/SourceLineInfo() is ambiguous
 219 
 220     /**
 221      * Obtains information about all source lines of a particular type that are
 222      * supported by the installed mixers.
 223      *
 224      * @param  info a {@code Line.Info} object that specifies the kind of lines
 225      *         about which information is requested
 226      * @return an array of {@code Line.Info} objects describing source lines
 227      *         matching the type requested. If no matching source lines are
 228      *         supported, an array of length 0 is returned.
 229      * @see Mixer#getSourceLineInfo(Line.Info)
 230      */
 231     public static Line.Info[] getSourceLineInfo(Line.Info info) {
 232 
 233         Vector<Line.Info> vector = new Vector<>();
 234         Line.Info[] currentInfoArray;
 235 
 236         Mixer mixer;
 237         Line.Info fullInfo = null;
 238         Mixer.Info[] infoArray = getMixerInfo();
 239 
 240         for (int i = 0; i < infoArray.length; i++) {
 241 
 242             mixer = getMixer(infoArray[i]);
 243 
 244             currentInfoArray = mixer.getSourceLineInfo(info);
 245             for (int j = 0; j < currentInfoArray.length; j++) {
 246                 vector.addElement(currentInfoArray[j]);
 247             }
 248         }
 249 
 250         Line.Info[] returnedArray = new Line.Info[vector.size()];
 251 
 252         for (int i = 0; i < returnedArray.length; i++) {
 253             returnedArray[i] = vector.get(i);
 254         }
 255 
 256         return returnedArray;
 257     }
 258 
 259     /**
 260      * Obtains information about all target lines of a particular type that are
 261      * supported by the installed mixers.
 262      *
 263      * @param  info a {@code Line.Info} object that specifies the kind of lines
 264      *         about which information is requested
 265      * @return an array of {@code Line.Info} objects describing target lines
 266      *         matching the type requested. If no matching target lines are
 267      *         supported, an array of length 0 is returned.
 268      * @see Mixer#getTargetLineInfo(Line.Info)
 269      */
 270     public static Line.Info[] getTargetLineInfo(Line.Info info) {
 271 
 272         Vector<Line.Info> vector = new Vector<>();
 273         Line.Info[] currentInfoArray;
 274 
 275         Mixer mixer;
 276         Line.Info fullInfo = null;
 277         Mixer.Info[] infoArray = getMixerInfo();
 278 
 279         for (int i = 0; i < infoArray.length; i++) {
 280 
 281             mixer = getMixer(infoArray[i]);
 282 
 283             currentInfoArray = mixer.getTargetLineInfo(info);
 284             for (int j = 0; j < currentInfoArray.length; j++) {
 285                 vector.addElement(currentInfoArray[j]);
 286             }
 287         }
 288 
 289         Line.Info[] returnedArray = new Line.Info[vector.size()];
 290 
 291         for (int i = 0; i < returnedArray.length; i++) {
 292             returnedArray[i] = vector.get(i);
 293         }
 294 
 295         return returnedArray;
 296     }
 297 
 298     /**
 299      * Indicates whether the system supports any lines that match the specified
 300      * {@code Line.Info} object. A line is supported if any installed mixer
 301      * supports it.
 302      *
 303      * @param  info a {@code Line.Info} object describing the line for which
 304      *         support is queried
 305      * @return {@code true} if at least one matching line is supported,
 306      *         otherwise {@code false}
 307      * @see Mixer#isLineSupported(Line.Info)
 308      */
 309     public static boolean isLineSupported(Line.Info info) {
 310 
 311         Mixer mixer;
 312         Mixer.Info[] infoArray = getMixerInfo();
 313 
 314         for (int i = 0; i < infoArray.length; i++) {
 315 
 316             if( infoArray[i] != null ) {
 317                 mixer = getMixer(infoArray[i]);
 318                 if (mixer.isLineSupported(info)) {
 319                     return true;
 320                 }
 321             }
 322         }
 323 
 324         return false;
 325     }
 326 
 327     /**
 328      * Obtains a line that matches the description in the specified
 329      * {@code Line.Info} object.
 330      * <p>
 331      * If a {@code DataLine} is requested, and {@code info} is an instance of
 332      * {@code DataLine.Info} specifying at least one fully qualified audio
 333      * format, the last one will be used as the default format of the returned
 334      * {@code DataLine}.
 335      * <p>
 336      * If system properties
 337      * {@code javax.sound.sampled.Clip},
 338      * {@code javax.sound.sampled.Port},
 339      * {@code javax.sound.sampled.SourceDataLine} and
 340      * {@code javax.sound.sampled.TargetDataLine} are defined or they are
 341      * defined in the file "sound.properties", they are used to retrieve default
 342      * lines. For details, refer to the {@link AudioSystem class description}.
 343      *
 344      * If the respective property is not set, or the mixer requested in the
 345      * property is not installed or does not provide the requested line, all
 346      * installed mixers are queried for the requested line type. A Line will be
 347      * returned from the first mixer providing the requested line type.
 348      *
 349      * @param  info a {@code Line.Info} object describing the desired kind of
 350      *         line
 351      * @return a line of the requested kind
 352      * @throws LineUnavailableException if a matching line is not available due
 353      *         to resource restrictions
 354      * @throws SecurityException if a matching line is not available due to
 355      *         security restrictions
 356      * @throws IllegalArgumentException if the system does not support at least
 357      *         one line matching the specified {@code Line.Info} object through
 358      *         any installed mixer
 359      */
 360     public static Line getLine(Line.Info info) throws LineUnavailableException {
 361         LineUnavailableException lue = null;
 362         List<MixerProvider> providers = getMixerProviders();
 363 
 364 
 365         // 1: try from default mixer for this line class
 366         try {
 367             Mixer mixer = getDefaultMixer(providers, info);
 368             if (mixer != null && mixer.isLineSupported(info)) {
 369                 return mixer.getLine(info);
 370             }
 371         } catch (LineUnavailableException e) {
 372             lue = e;
 373         } catch (IllegalArgumentException iae) {
 374             // must not happen... but better to catch it here,
 375             // if plug-ins are badly written
 376         }
 377 
 378 
 379         // 2: if that doesn't work, try to find any mixing mixer
 380         for(int i = 0; i < providers.size(); i++) {
 381             MixerProvider provider = providers.get(i);
 382             Mixer.Info[] infos = provider.getMixerInfo();
 383 
 384             for (int j = 0; j < infos.length; j++) {
 385                 try {
 386                     Mixer mixer = provider.getMixer(infos[j]);
 387                     // see if this is an appropriate mixer which can mix
 388                     if (isAppropriateMixer(mixer, info, true)) {
 389                         return mixer.getLine(info);
 390                     }
 391                 } catch (LineUnavailableException e) {
 392                     lue = e;
 393                 } catch (IllegalArgumentException iae) {
 394                     // must not happen... but better to catch it here,
 395                     // if plug-ins are badly written
 396                 }
 397             }
 398         }
 399 
 400 
 401         // 3: if that didn't work, try to find any non-mixing mixer
 402         for(int i = 0; i < providers.size(); i++) {
 403             MixerProvider provider = providers.get(i);
 404             Mixer.Info[] infos = provider.getMixerInfo();
 405             for (int j = 0; j < infos.length; j++) {
 406                 try {
 407                     Mixer mixer = provider.getMixer(infos[j]);
 408                     // see if this is an appropriate mixer which can mix
 409                     if (isAppropriateMixer(mixer, info, false)) {
 410                         return mixer.getLine(info);
 411                     }
 412                 } catch (LineUnavailableException e) {
 413                     lue = e;
 414                 } catch (IllegalArgumentException iae) {
 415                     // must not happen... but better to catch it here,
 416                     // if plug-ins are badly written
 417                 }
 418             }
 419         }
 420 
 421         // if this line was supported but was not available, throw the last
 422         // LineUnavailableException we got (??).
 423         if (lue != null) {
 424             throw lue;
 425         }
 426 
 427         // otherwise, the requested line was not supported, so throw
 428         // an Illegal argument exception
 429         throw new IllegalArgumentException("No line matching " +
 430                                            info.toString() + " is supported.");
 431     }
 432 
 433     /**
 434      * Obtains a clip that can be used for playing back an audio file or an
 435      * audio stream. The returned clip will be provided by the default system
 436      * mixer, or, if not possible, by any other mixer installed in the system
 437      * that supports a {@code Clip} object.
 438      * <p>
 439      * The returned clip must be opened with the {@code open(AudioFormat)} or
 440      * {@code open(AudioInputStream)} method.
 441      * <p>
 442      * This is a high-level method that uses {@code getMixer} and
 443      * {@code getLine} internally.
 444      * <p>
 445      * If the system property {@code javax.sound.sampled.Clip} is defined or it
 446      * is defined in the file "sound.properties", it is used to retrieve the
 447      * default clip. For details, refer to the
 448      * {@link AudioSystem class description}.
 449      *
 450      * @return the desired clip object
 451      * @throws LineUnavailableException if a clip object is not available due to
 452      *         resource restrictions
 453      * @throws SecurityException if a clip object is not available due to
 454      *         security restrictions
 455      * @throws IllegalArgumentException if the system does not support at least
 456      *         one clip instance through any installed mixer
 457      * @see #getClip(Mixer.Info)
 458      * @since 1.5
 459      */
 460     public static Clip getClip() throws LineUnavailableException{
 461         AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
 462                                              AudioSystem.NOT_SPECIFIED,
 463                                              16, 2, 4,
 464                                              AudioSystem.NOT_SPECIFIED, true);
 465         DataLine.Info info = new DataLine.Info(Clip.class, format);
 466         return (Clip) AudioSystem.getLine(info);
 467     }
 468 
 469     /**
 470      * Obtains a clip from the specified mixer that can be used for playing back
 471      * an audio file or an audio stream.
 472      * <p>
 473      * The returned clip must be opened with the {@code open(AudioFormat)} or
 474      * {@code open(AudioInputStream)} method.
 475      * <p>
 476      * This is a high-level method that uses {@code getMixer} and
 477      * {@code getLine} internally.
 478      *
 479      * @param  mixerInfo a {@code Mixer.Info} object representing the desired
 480      *         mixer, or {@code null} for the system default mixer
 481      * @return a clip object from the specified mixer
 482      *
 483      * @throws LineUnavailableException if a clip is not available from this
 484      *         mixer due to resource restrictions
 485      * @throws SecurityException if a clip is not available from this mixer due
 486      *         to security restrictions
 487      * @throws IllegalArgumentException if the system does not support at least
 488      *         one clip through the specified mixer
 489      * @see #getClip()
 490      * @since 1.5
 491      */
 492     public static Clip getClip(Mixer.Info mixerInfo) throws LineUnavailableException{
 493         AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
 494                                              AudioSystem.NOT_SPECIFIED,
 495                                              16, 2, 4,
 496                                              AudioSystem.NOT_SPECIFIED, true);
 497         DataLine.Info info = new DataLine.Info(Clip.class, format);
 498         Mixer mixer = AudioSystem.getMixer(mixerInfo);
 499         return (Clip) mixer.getLine(info);
 500     }
 501 
 502     /**
 503      * Obtains a source data line that can be used for playing back audio data
 504      * in the format specified by the {@code AudioFormat} object. The returned
 505      * line will be provided by the default system mixer, or, if not possible,
 506      * by any other mixer installed in the system that supports a matching
 507      * {@code SourceDataLine} object.
 508      * <p>
 509      * The returned line should be opened with the {@code open(AudioFormat)} or
 510      * {@code open(AudioFormat, int)} method.
 511      * <p>
 512      * This is a high-level method that uses {@code getMixer} and
 513      * {@code getLine} internally.
 514      * <p>
 515      * The returned {@code SourceDataLine}'s default audio format will be
 516      * initialized with {@code format}.
 517      * <p>
 518      * If the system property {@code javax.sound.sampled.SourceDataLine} is
 519      * defined or it is defined in the file "sound.properties", it is used to
 520      * retrieve the default source data line. For details, refer to the
 521      * {@link AudioSystem class description}.
 522      *
 523      * @param  format an {@code AudioFormat} object specifying the supported
 524      *         audio format of the returned line, or {@code null} for any audio
 525      *         format
 526      * @return the desired {@code SourceDataLine} object
 527      * @throws LineUnavailableException if a matching source data line is not
 528      *         available due to resource restrictions
 529      * @throws SecurityException if a matching source data line is not available
 530      *         due to security restrictions
 531      * @throws IllegalArgumentException if the system does not support at least
 532      *         one source data line supporting the specified audio format
 533      *         through any installed mixer
 534      * @see #getSourceDataLine(AudioFormat, Mixer.Info)
 535      * @since 1.5
 536      */
 537     public static SourceDataLine getSourceDataLine(AudioFormat format)
 538         throws LineUnavailableException{
 539         DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
 540         return (SourceDataLine) AudioSystem.getLine(info);
 541     }
 542 
 543     /**
 544      * Obtains a source data line that can be used for playing back audio data
 545      * in the format specified by the {@code AudioFormat} object, provided by
 546      * the mixer specified by the {@code Mixer.Info} object.
 547      * <p>
 548      * The returned line should be opened with the {@code open(AudioFormat)} or
 549      * {@code open(AudioFormat, int)} method.
 550      * <p>
 551      * This is a high-level method that uses {@code getMixer} and
 552      * {@code getLine} internally.
 553      * <p>
 554      * The returned {@code SourceDataLine}'s default audio format will be
 555      * initialized with {@code format}.
 556      *
 557      * @param  format an {@code AudioFormat} object specifying the supported
 558      *         audio format of the returned line, or {@code null} for any audio
 559      *         format
 560      * @param  mixerinfo a {@code Mixer.Info} object representing the desired
 561      *         mixer, or {@code null} for the system default mixer
 562      * @return the desired {@code SourceDataLine} object
 563      * @throws LineUnavailableException if a matching source data line is not
 564      *         available from the specified mixer due to resource restrictions
 565      * @throws SecurityException if a matching source data line is not available
 566      *         from the specified mixer due to security restrictions
 567      * @throws IllegalArgumentException if the specified mixer does not support
 568      *         at least one source data line supporting the specified audio
 569      *         format
 570      * @see #getSourceDataLine(AudioFormat)
 571      * @since 1.5
 572      */
 573     public static SourceDataLine getSourceDataLine(AudioFormat format,
 574                                                    Mixer.Info mixerinfo)
 575         throws LineUnavailableException{
 576         DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
 577         Mixer mixer = AudioSystem.getMixer(mixerinfo);
 578         return (SourceDataLine) mixer.getLine(info);
 579     }
 580 
 581     /**
 582      * Obtains a target data line that can be used for recording audio data in
 583      * the format specified by the {@code AudioFormat} object. The returned line
 584      * will be provided by the default system mixer, or, if not possible, by any
 585      * other mixer installed in the system that supports a matching
 586      * {@code TargetDataLine} object.
 587      * <p>
 588      * The returned line should be opened with the {@code open(AudioFormat)} or
 589      * {@code open(AudioFormat, int)} method.
 590      * <p>
 591      * This is a high-level method that uses {@code getMixer} and
 592      * {@code getLine} internally.
 593      * <p>
 594      * The returned {@code TargetDataLine}'s default audio format will be
 595      * initialized with {@code format}.
 596      * <p>
 597      * If the system property {@code javax.sound.sampled.TargetDataLine} is
 598      * defined or it is defined in the file "sound.properties", it is used to
 599      * retrieve the default target data line. For details, refer to the
 600      * {@link AudioSystem class description}.
 601      *
 602      * @param  format an {@code AudioFormat} object specifying the supported
 603      *         audio format of the returned line, or {@code null} for any audio
 604      *         format
 605      * @return the desired {@code TargetDataLine} object
 606      * @throws LineUnavailableException if a matching target data line is not
 607      *         available due to resource restrictions
 608      * @throws SecurityException if a matching target data line is not available
 609      *         due to security restrictions
 610      * @throws IllegalArgumentException if the system does not support at least
 611      *         one target data line supporting the specified audio format
 612      *         through any installed mixer
 613      * @see #getTargetDataLine(AudioFormat, Mixer.Info)
 614      * @see AudioPermission
 615      * @since 1.5
 616      */
 617     public static TargetDataLine getTargetDataLine(AudioFormat format)
 618         throws LineUnavailableException{
 619 
 620         DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
 621         return (TargetDataLine) AudioSystem.getLine(info);
 622     }
 623 
 624     /**
 625      * Obtains a target data line that can be used for recording audio data in
 626      * the format specified by the {@code AudioFormat} object, provided by the
 627      * mixer specified by the {@code Mixer.Info} object.
 628      * <p>
 629      * The returned line should be opened with the {@code open(AudioFormat)} or
 630      * {@code open(AudioFormat, int)} method.
 631      * <p>
 632      * This is a high-level method that uses {@code getMixer} and
 633      * {@code getLine} internally.
 634      * <p>
 635      * The returned {@code TargetDataLine}'s default audio format will be
 636      * initialized with {@code format}.
 637      *
 638      * @param  format an {@code AudioFormat} object specifying the supported
 639      *         audio format of the returned line, or {@code null} for any audio
 640      *         format
 641      * @param  mixerinfo a {@code Mixer.Info} object representing the desired
 642      *         mixer, or {@code null} for the system default mixer
 643      * @return the desired {@code TargetDataLine} object
 644      * @throws LineUnavailableException if a matching target data line is not
 645      *         available from the specified mixer due to resource restrictions
 646      * @throws SecurityException if a matching target data line is not available
 647      *         from the specified mixer due to security restrictions
 648      * @throws IllegalArgumentException if the specified mixer does not support
 649      *         at least one target data line supporting the specified audio
 650      *         format
 651      * @see #getTargetDataLine(AudioFormat)
 652      * @see AudioPermission
 653      * @since 1.5
 654      */
 655     public static TargetDataLine getTargetDataLine(AudioFormat format,
 656                                                    Mixer.Info mixerinfo)
 657         throws LineUnavailableException {
 658 
 659         DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
 660         Mixer mixer = AudioSystem.getMixer(mixerinfo);
 661         return (TargetDataLine) mixer.getLine(info);
 662     }
 663 
 664     // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
 665 
 666     /**
 667      * Obtains the encodings that the system can obtain from an audio input
 668      * stream with the specified encoding using the set of installed format
 669      * converters.
 670      *
 671      * @param  sourceEncoding the encoding for which conversion support is
 672      *         queried
 673      * @return array of encodings. If {@code sourceEncoding}is not supported, an
 674      *         array of length 0 is returned. Otherwise, the array will have a
 675      *         length of at least 1, representing {@code sourceEncoding}
 676      *         (no conversion).
 677      * @throws NullPointerException if {@code sourceEncoding} is {@code null}
 678      */
 679     public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
 680         Objects.requireNonNull(sourceEncoding);
 681 
 682         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 683         Vector<AudioFormat.Encoding> encodings = new Vector<>();
 684 
 685         AudioFormat.Encoding encs[] = null;
 686 
 687         // gather from all the codecs
 688         for(int i=0; i<codecs.size(); i++ ) {
 689             FormatConversionProvider codec = codecs.get(i);
 690             if( codec.isSourceEncodingSupported( sourceEncoding ) ) {
 691                 encs = codec.getTargetEncodings();
 692                 for (int j = 0; j < encs.length; j++) {
 693                     encodings.addElement( encs[j] );
 694                 }
 695             }
 696         }
 697         if (!encodings.contains(sourceEncoding)) {
 698             encodings.addElement(sourceEncoding);
 699         }
 700 
 701         return encodings.toArray(new AudioFormat.Encoding[encodings.size()]);
 702     }
 703 
 704     // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
 705 
 706     /**
 707      * Obtains the encodings that the system can obtain from an audio input
 708      * stream with the specified format using the set of installed format
 709      * converters.
 710      *
 711      * @param  sourceFormat the audio format for which conversion is queried
 712      * @return array of encodings. If {@code sourceFormat}is not supported, an
 713      *         array of length 0 is returned. Otherwise, the array will have a
 714      *         length of at least 1, representing the encoding of
 715      *         {@code sourceFormat} (no conversion).
 716      * @throws NullPointerException if {@code sourceFormat} is {@code null}
 717      */
 718     public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat) {
 719         Objects.requireNonNull(sourceFormat);
 720 
 721         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 722         List<AudioFormat.Encoding> encs = new ArrayList<>();
 723 
 724         // gather from all the codecs
 725         for (final FormatConversionProvider codec : codecs) {
 726             Collections.addAll(encs, codec.getTargetEncodings(sourceFormat));
 727         }
 728 
 729         if (!encs.contains(sourceFormat.getEncoding())) {
 730             encs.add(sourceFormat.getEncoding());
 731         }
 732 
 733         return encs.toArray(new AudioFormat.Encoding[encs.size()]);
 734     }
 735 
 736     /**
 737      * Indicates whether an audio input stream of the specified encoding can be
 738      * obtained from an audio input stream that has the specified format.
 739      *
 740      * @param  targetEncoding the desired encoding after conversion
 741      * @param  sourceFormat the audio format before conversion
 742      * @return {@code true} if the conversion is supported, otherwise
 743      *         {@code false}
 744      * @throws NullPointerException if {@code targetEncoding} or
 745      *         {@code sourceFormat} are {@code null}
 746      */
 747     public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
 748         Objects.requireNonNull(targetEncoding);
 749         Objects.requireNonNull(sourceFormat);
 750         if (sourceFormat.getEncoding().equals(targetEncoding)) {
 751             return true;
 752         }
 753 
 754         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 755 
 756         for(int i=0; i<codecs.size(); i++ ) {
 757             FormatConversionProvider codec = codecs.get(i);
 758             if(codec.isConversionSupported(targetEncoding,sourceFormat) ) {
 759                 return true;
 760             }
 761         }
 762         return false;
 763     }
 764 
 765     /**
 766      * Obtains an audio input stream of the indicated encoding, by converting
 767      * the provided audio input stream.
 768      *
 769      * @param  targetEncoding the desired encoding after conversion
 770      * @param  sourceStream the stream to be converted
 771      * @return an audio input stream of the indicated encoding
 772      * @throws IllegalArgumentException if the conversion is not supported
 773      * @throws NullPointerException if {@code targetEncoding} or
 774      *         {@code sourceStream} are {@code null}
 775      * @see #getTargetEncodings(AudioFormat.Encoding)
 776      * @see #getTargetEncodings(AudioFormat)
 777      * @see #isConversionSupported(AudioFormat.Encoding, AudioFormat)
 778      * @see #getAudioInputStream(AudioFormat, AudioInputStream)
 779      */
 780     public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
 781                                                        AudioInputStream sourceStream) {
 782         Objects.requireNonNull(targetEncoding);
 783         Objects.requireNonNull(sourceStream);
 784         if (sourceStream.getFormat().getEncoding().equals(targetEncoding)) {
 785             return sourceStream;
 786         }
 787 
 788         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 789 
 790         for(int i = 0; i < codecs.size(); i++) {
 791             FormatConversionProvider codec = codecs.get(i);
 792             if( codec.isConversionSupported( targetEncoding, sourceStream.getFormat() ) ) {
 793                 return codec.getAudioInputStream( targetEncoding, sourceStream );
 794             }
 795         }
 796         // we ran out of options, throw an exception
 797         throw new IllegalArgumentException("Unsupported conversion: " + targetEncoding + " from " + sourceStream.getFormat());
 798     }
 799 
 800     /**
 801      * Obtains the formats that have a particular encoding and that the system
 802      * can obtain from a stream of the specified format using the set of
 803      * installed format converters.
 804      *
 805      * @param  targetEncoding the desired encoding after conversion
 806      * @param  sourceFormat the audio format before conversion
 807      * @return array of formats. If no formats of the specified encoding are
 808      *         supported, an array of length 0 is returned.
 809      * @throws NullPointerException if {@code targetEncoding} or
 810      *         {@code sourceFormat} are {@code null}
 811      */
 812     public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
 813         Objects.requireNonNull(targetEncoding);
 814         Objects.requireNonNull(sourceFormat);
 815 
 816         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 817         List<AudioFormat> formats = new ArrayList<>();
 818 
 819         boolean matchFound = false;
 820         // gather from all the codecs
 821         for (final FormatConversionProvider codec : codecs) {
 822             AudioFormat[] elements = codec
 823                     .getTargetFormats(targetEncoding, sourceFormat);
 824             for (AudioFormat format : elements) {
 825                 formats.add(format);
 826                 if (sourceFormat.matches(format)) {
 827                     matchFound = true;
 828                 }
 829             }
 830         }
 831 
 832         if (targetEncoding.equals(sourceFormat.getEncoding())) {
 833             if (!matchFound) {
 834                 formats.add(sourceFormat);
 835             }
 836         }
 837         return formats.toArray(new AudioFormat[formats.size()]);
 838     }
 839 
 840     /**
 841      * Indicates whether an audio input stream of a specified format can be
 842      * obtained from an audio input stream of another specified format.
 843      *
 844      * @param  targetFormat the desired audio format after conversion
 845      * @param  sourceFormat the audio format before conversion
 846      * @return {@code true} if the conversion is supported, otherwise
 847      *         {@code false}
 848      * @throws NullPointerException if {@code targetFormat} or
 849      *         {@code sourceFormat} are {@code null}
 850      */
 851     public static boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) {
 852         Objects.requireNonNull(targetFormat);
 853         Objects.requireNonNull(sourceFormat);
 854         if (sourceFormat.matches(targetFormat)) {
 855             return true;
 856         }
 857 
 858         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 859 
 860         for(int i=0; i<codecs.size(); i++ ) {
 861             FormatConversionProvider codec = codecs.get(i);
 862             if(codec.isConversionSupported(targetFormat, sourceFormat) ) {
 863                 return true;
 864             }
 865         }
 866         return false;
 867     }
 868 
 869     /**
 870      * Obtains an audio input stream of the indicated format, by converting the
 871      * provided audio input stream.
 872      *
 873      * @param  targetFormat the desired audio format after conversion
 874      * @param  sourceStream the stream to be converted
 875      * @return an audio input stream of the indicated format
 876      * @throws IllegalArgumentException if the conversion is not supported
 877      * @throws NullPointerException if {@code targetFormat} or
 878      *         {@code sourceStream} are {@code null}
 879      * @see #getTargetEncodings(AudioFormat)
 880      * @see #getTargetFormats(AudioFormat.Encoding, AudioFormat)
 881      * @see #isConversionSupported(AudioFormat, AudioFormat)
 882      * @see #getAudioInputStream(AudioFormat.Encoding, AudioInputStream)
 883      */
 884     public static AudioInputStream getAudioInputStream(AudioFormat targetFormat,
 885                                                        AudioInputStream sourceStream) {
 886         if (sourceStream.getFormat().matches(targetFormat)) {
 887             return sourceStream;
 888         }
 889 
 890         List<FormatConversionProvider> codecs = getFormatConversionProviders();
 891 
 892         for(int i = 0; i < codecs.size(); i++) {
 893             FormatConversionProvider codec = codecs.get(i);
 894             if(codec.isConversionSupported(targetFormat,sourceStream.getFormat()) ) {
 895                 return codec.getAudioInputStream(targetFormat,sourceStream);
 896             }
 897         }
 898 
 899         // we ran out of options...
 900         throw new IllegalArgumentException("Unsupported conversion: " + targetFormat + " from " + sourceStream.getFormat());
 901     }
 902 
 903     /**
 904      * Obtains the audio file format of the provided input stream. The stream
 905      * must point to valid audio file data. The implementation of this method
 906      * may require multiple parsers to examine the stream to determine whether
 907      * they support it. These parsers must be able to mark the stream, read
 908      * enough data to determine whether they support the stream, and reset the
 909      * stream's read pointer to its original position. If the input stream does
 910      * not support these operations, this method may fail with an
 911      * {@code IOException}.
 912      *
 913      * @param  stream the input stream from which file format information should
 914      *         be extracted
 915      * @return an {@code AudioFileFormat} object describing the stream's audio
 916      *         file format
 917      * @throws UnsupportedAudioFileException if the stream does not point to
 918      *         valid audio file data recognized by the system
 919      * @throws IOException if an input/output exception occurs
 920      * @throws NullPointerException if {@code stream} is {@code null}
 921      * @see InputStream#markSupported
 922      * @see InputStream#mark
 923      */
 924     public static AudioFileFormat getAudioFileFormat(final InputStream stream)
 925             throws UnsupportedAudioFileException, IOException {
 926         Objects.requireNonNull(stream);
 927 
 928         for (final AudioFileReader reader : getAudioFileReaders()) {
 929             try {
 930                 return reader.getAudioFileFormat(stream);
 931             } catch (final UnsupportedAudioFileException ignored) {
 932             }
 933         }
 934         throw new UnsupportedAudioFileException("Stream of unsupported format");
 935     }
 936 
 937     /**
 938      * Obtains the audio file format of the specified URL. The URL must point to
 939      * valid audio file data.
 940      *
 941      * @param  url the URL from which file format information should be
 942      *         extracted
 943      * @return an {@code AudioFileFormat} object describing the audio file
 944      *         format
 945      * @throws UnsupportedAudioFileException if the URL does not point to valid
 946      *         audio file data recognized by the system
 947      * @throws IOException if an input/output exception occurs
 948      * @throws NullPointerException if {@code url} is {@code null}
 949      */
 950     public static AudioFileFormat getAudioFileFormat(final URL url)
 951             throws UnsupportedAudioFileException, IOException {
 952         Objects.requireNonNull(url);
 953 
 954         for (final AudioFileReader reader : getAudioFileReaders()) {
 955             try {
 956                 return reader.getAudioFileFormat(url);
 957             } catch (final UnsupportedAudioFileException ignored) {
 958             }
 959         }
 960         throw new UnsupportedAudioFileException("URL of unsupported format");
 961     }
 962 
 963     /**
 964      * Obtains the audio file format of the specified {@code File}. The
 965      * {@code File} must point to valid audio file data.
 966      *
 967      * @param  file the {@code File} from which file format information should
 968      *         be extracted
 969      * @return an {@code AudioFileFormat} object describing the audio file
 970      *         format
 971      * @throws UnsupportedAudioFileException if the {@code File} does not point
 972      *         to valid audio file data recognized by the system
 973      * @throws IOException if an I/O exception occurs
 974      * @throws NullPointerException if {@code file} is {@code null}
 975      */
 976     public static AudioFileFormat getAudioFileFormat(final File file)
 977             throws UnsupportedAudioFileException, IOException {
 978         Objects.requireNonNull(file);
 979 
 980         for (final AudioFileReader reader : getAudioFileReaders()) {
 981             try {
 982                 return reader.getAudioFileFormat(file);
 983             } catch (final UnsupportedAudioFileException ignored) {
 984             }
 985         }
 986         throw new UnsupportedAudioFileException("File of unsupported format");
 987     }
 988 
 989     /**
 990      * Obtains an audio input stream from the provided input stream. The stream
 991      * must point to valid audio file data. The implementation of this method
 992      * may require multiple parsers to examine the stream to determine whether
 993      * they support it. These parsers must be able to mark the stream, read
 994      * enough data to determine whether they support the stream, and reset the
 995      * stream's read pointer to its original position. If the input stream does
 996      * not support these operation, this method may fail with an
 997      * {@code IOException}.
 998      *
 999      * @param  stream the input stream from which the {@code AudioInputStream}
1000      *         should be constructed
1001      * @return an {@code AudioInputStream} object based on the audio file data
1002      *         contained in the input stream
1003      * @throws UnsupportedAudioFileException if the stream does not point to
1004      *         valid audio file data recognized by the system
1005      * @throws IOException if an I/O exception occurs
1006      * @throws NullPointerException if {@code stream} is {@code null}
1007      * @see InputStream#markSupported
1008      * @see InputStream#mark
1009      */
1010     public static AudioInputStream getAudioInputStream(final InputStream stream)
1011             throws UnsupportedAudioFileException, IOException {
1012         Objects.requireNonNull(stream);
1013 
1014         for (final AudioFileReader reader : getAudioFileReaders()) {
1015             try {
1016                 return reader.getAudioInputStream(stream);
1017             } catch (final UnsupportedAudioFileException ignored) {
1018             }
1019         }
1020         throw new UnsupportedAudioFileException("Stream of unsupported format");
1021     }
1022 
1023     /**
1024      * Obtains an audio input stream from the URL provided. The URL must point
1025      * to valid audio file data.
1026      *
1027      * @param  url the URL for which the {@code AudioInputStream} should be
1028      *         constructed
1029      * @return an {@code AudioInputStream} object based on the audio file data
1030      *         pointed to by the URL
1031      * @throws UnsupportedAudioFileException if the URL does not point to valid
1032      *         audio file data recognized by the system
1033      * @throws IOException if an I/O exception occurs
1034      * @throws NullPointerException if {@code url} is {@code null}
1035      */
1036     public static AudioInputStream getAudioInputStream(final URL url)
1037             throws UnsupportedAudioFileException, IOException {
1038         Objects.requireNonNull(url);
1039 
1040         for (final AudioFileReader reader : getAudioFileReaders()) {
1041             try {
1042                 return reader.getAudioInputStream(url);
1043             } catch (final UnsupportedAudioFileException ignored) {
1044             }
1045         }
1046         throw new UnsupportedAudioFileException("URL of unsupported format");
1047     }
1048 
1049     /**
1050      * Obtains an audio input stream from the provided {@code File}. The
1051      * {@code File} must point to valid audio file data.
1052      *
1053      * @param  file the {@code File} for which the {@code AudioInputStream}
1054      *         should be constructed
1055      * @return an {@code AudioInputStream} object based on the audio file data
1056      *         pointed to by the {@code File}
1057      * @throws UnsupportedAudioFileException if the {@code File} does not point
1058      *         to valid audio file data recognized by the system
1059      * @throws IOException if an I/O exception occurs
1060      * @throws NullPointerException if {@code file} is {@code null}
1061      */
1062     public static AudioInputStream getAudioInputStream(final File file)
1063             throws UnsupportedAudioFileException, IOException {
1064         Objects.requireNonNull(file);
1065 
1066         for (final AudioFileReader reader : getAudioFileReaders()) {
1067             try {
1068                 return reader.getAudioInputStream(file);
1069             } catch (final UnsupportedAudioFileException ignored) {
1070             }
1071         }
1072         throw new UnsupportedAudioFileException("File of unsupported format");
1073     }
1074 
1075     /**
1076      * Obtains the file types for which file writing support is provided by the
1077      * system.
1078      *
1079      * @return array of unique file types. If no file types are supported, an
1080      *         array of length 0 is returned.
1081      */
1082     public static AudioFileFormat.Type[] getAudioFileTypes() {
1083         List<AudioFileWriter> providers = getAudioFileWriters();
1084         Set<AudioFileFormat.Type> returnTypesSet = new HashSet<>();
1085 
1086         for(int i=0; i < providers.size(); i++) {
1087             AudioFileWriter writer = providers.get(i);
1088             AudioFileFormat.Type[] fileTypes = writer.getAudioFileTypes();
1089             for(int j=0; j < fileTypes.length; j++) {
1090                 returnTypesSet.add(fileTypes[j]);
1091             }
1092         }
1093         AudioFileFormat.Type returnTypes[] =
1094             returnTypesSet.toArray(new AudioFileFormat.Type[0]);
1095         return returnTypes;
1096     }
1097 
1098     /**
1099      * Indicates whether file writing support for the specified file type is
1100      * provided by the system.
1101      *
1102      * @param  fileType the file type for which write capabilities are queried
1103      * @return {@code true} if the file type is supported, otherwise
1104      *         {@code false}
1105      * @throws NullPointerException if {@code fileType} is {@code null}
1106      */
1107     public static boolean isFileTypeSupported(AudioFileFormat.Type fileType) {
1108         Objects.requireNonNull(fileType);
1109         List<AudioFileWriter> providers = getAudioFileWriters();
1110 
1111         for(int i=0; i < providers.size(); i++) {
1112             AudioFileWriter writer = providers.get(i);
1113             if (writer.isFileTypeSupported(fileType)) {
1114                 return true;
1115             }
1116         }
1117         return false;
1118     }
1119 
1120     /**
1121      * Obtains the file types that the system can write from the audio input
1122      * stream specified.
1123      *
1124      * @param  stream the audio input stream for which audio file type
1125      *         support is queried
1126      * @return array of file types. If no file types are supported, an array of
1127      *         length 0 is returned.
1128      * @throws NullPointerException if {@code stream} is {@code null}
1129      */
1130     public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) {
1131         Objects.requireNonNull(stream);
1132         List<AudioFileWriter> providers = getAudioFileWriters();
1133         Set<AudioFileFormat.Type> returnTypesSet = new HashSet<>();
1134 
1135         for(int i=0; i < providers.size(); i++) {
1136             AudioFileWriter writer = providers.get(i);
1137             AudioFileFormat.Type[] fileTypes = writer.getAudioFileTypes(stream);
1138             for(int j=0; j < fileTypes.length; j++) {
1139                 returnTypesSet.add(fileTypes[j]);
1140             }
1141         }
1142         AudioFileFormat.Type returnTypes[] =
1143             returnTypesSet.toArray(new AudioFileFormat.Type[0]);
1144         return returnTypes;
1145     }
1146 
1147     /**
1148      * Indicates whether an audio file of the specified file type can be written
1149      * from the indicated audio input stream.
1150      *
1151      * @param  fileType the file type for which write capabilities are queried
1152      * @param  stream the stream for which file-writing support is queried
1153      * @return {@code true} if the file type is supported for this audio input
1154      *         stream, otherwise {@code false}
1155      * @throws NullPointerException if {@code fileType} or {@code stream} are
1156      *         {@code null}
1157      */
1158     public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
1159                                               AudioInputStream stream) {
1160         Objects.requireNonNull(fileType);
1161         Objects.requireNonNull(stream);
1162         List<AudioFileWriter> providers = getAudioFileWriters();
1163 
1164         for(int i=0; i < providers.size(); i++) {
1165             AudioFileWriter writer = providers.get(i);
1166             if(writer.isFileTypeSupported(fileType, stream)) {
1167                 return true;
1168             }
1169         }
1170         return false;
1171     }
1172 
1173     /**
1174      * Writes a stream of bytes representing an audio file of the specified file
1175      * type to the output stream provided. Some file types require that the
1176      * length be written into the file header; such files cannot be written from
1177      * start to finish unless the length is known in advance. An attempt to
1178      * write a file of such a type will fail with an IOException if the length
1179      * in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
1180      *
1181      * @param  stream the audio input stream containing audio data to be written
1182      *         to the file
1183      * @param  fileType the kind of audio file to write
1184      * @param  out the stream to which the file data should be written
1185      * @return the number of bytes written to the output stream
1186      * @throws IOException if an input/output exception occurs
1187      * @throws IllegalArgumentException if the file type is not supported by the
1188      *         system
1189      * @throws NullPointerException if {@code stream} or {@code fileType} or
1190      *         {@code out} are {@code null}
1191      * @see #isFileTypeSupported
1192      * @see #getAudioFileTypes
1193      */
1194     public static int write(final AudioInputStream stream,
1195                             final AudioFileFormat.Type fileType,
1196                             final OutputStream out) throws IOException {
1197         Objects.requireNonNull(stream);
1198         Objects.requireNonNull(fileType);
1199         Objects.requireNonNull(out);
1200 
1201         for (final AudioFileWriter writer : getAudioFileWriters()) {
1202             try {
1203                 return writer.write(stream, fileType, out);
1204             } catch (final IllegalArgumentException ignored) {
1205                 // thrown if this provider cannot write the stream, try next
1206             }
1207         }
1208         // "File type " + type + " not supported."
1209         throw new IllegalArgumentException(
1210                 "could not write audio file: file type not supported: "
1211                         + fileType);
1212     }
1213 
1214     /**
1215      * Writes a stream of bytes representing an audio file of the specified file
1216      * type to the external file provided.
1217      *
1218      * @param  stream the audio input stream containing audio data to be written
1219      *         to the file
1220      * @param  fileType the kind of audio file to write
1221      * @param  out the external file to which the file data should be written
1222      * @return the number of bytes written to the file
1223      * @throws IOException if an I/O exception occurs
1224      * @throws IllegalArgumentException if the file type is not supported by the
1225      *         system
1226      * @throws NullPointerException if {@code stream} or {@code fileType} or
1227      *         {@code out} are {@code null}
1228      * @see #isFileTypeSupported
1229      * @see #getAudioFileTypes
1230      */
1231     public static int write(final AudioInputStream stream,
1232                             final AudioFileFormat.Type fileType,
1233                             final File out) throws IOException {
1234         Objects.requireNonNull(stream);
1235         Objects.requireNonNull(fileType);
1236         Objects.requireNonNull(out);
1237 
1238         for (final AudioFileWriter writer : getAudioFileWriters()) {
1239             try {
1240                 return writer.write(stream, fileType, out);
1241             } catch (final IllegalArgumentException ignored) {
1242                 // thrown if this provider cannot write the stream, try next
1243             }
1244         }
1245         throw new IllegalArgumentException(
1246                 "could not write audio file: file type not supported: "
1247                         + fileType);
1248     }
1249 
1250     // METHODS FOR INTERNAL IMPLEMENTATION USE
1251 
1252     /**
1253      * Obtains the set of MixerProviders on the system.
1254      */
1255     @SuppressWarnings("unchecked")
1256     private static List<MixerProvider> getMixerProviders() {
1257         return (List<MixerProvider>) getProviders(MixerProvider.class);
1258     }
1259 
1260     /**
1261      * Obtains the set of format converters (codecs, transcoders, etc.) that are
1262      * currently installed on the system.
1263      *
1264      * @return an array of {@link FormatConversionProvider} objects representing
1265      *         the available format converters. If no format converters readers
1266      *         are available on the system, an array of length 0 is returned.
1267      */
1268     @SuppressWarnings("unchecked")
1269     private static List<FormatConversionProvider> getFormatConversionProviders() {
1270         return (List<FormatConversionProvider>) getProviders(FormatConversionProvider.class);
1271     }
1272 
1273     /**
1274      * Obtains the set of audio file readers that are currently installed on the
1275      * system.
1276      *
1277      * @return a List of {@link AudioFileReader} objects representing the
1278      *         installed audio file readers. If no audio file readers are
1279      *         available on the system, an empty List is returned.
1280      */
1281     @SuppressWarnings("unchecked")
1282     private static List<AudioFileReader> getAudioFileReaders() {
1283         return (List<AudioFileReader>)getProviders(AudioFileReader.class);
1284     }
1285 
1286     /**
1287      * Obtains the set of audio file writers that are currently installed on the
1288      * system.
1289      *
1290      * @return a List of {@link AudioFileWriter} objects representing the
1291      *         available audio file writers. If no audio file writers are
1292      *         available on the system, an empty List is returned.
1293      */
1294     @SuppressWarnings("unchecked")
1295     private static List<AudioFileWriter> getAudioFileWriters() {
1296         return (List<AudioFileWriter>)getProviders(AudioFileWriter.class);
1297     }
1298 
1299     /**
1300      * Attempts to locate and return a default Mixer that provides lines of the
1301      * specified type.
1302      *
1303      * @param  providers the installed mixer providers
1304      * @param  info The requested line type TargetDataLine.class, Clip.class or
1305      *         Port.class
1306      * @return a Mixer that matches the requirements, or null if no default
1307      *         mixer found
1308      */
1309     private static Mixer getDefaultMixer(List<MixerProvider> providers, Line.Info info) {
1310         Class<?> lineClass = info.getLineClass();
1311         String providerClassName = JDK13Services.getDefaultProviderClassName(lineClass);
1312         String instanceName = JDK13Services.getDefaultInstanceName(lineClass);
1313         Mixer mixer;
1314 
1315         if (providerClassName != null) {
1316             MixerProvider defaultProvider = getNamedProvider(providerClassName, providers);
1317             if (defaultProvider != null) {
1318                 if (instanceName != null) {
1319                     mixer = getNamedMixer(instanceName, defaultProvider, info);
1320                     if (mixer != null) {
1321                         return mixer;
1322                     }
1323                 } else {
1324                     mixer = getFirstMixer(defaultProvider, info,
1325                                           false /* mixing not required*/);
1326                     if (mixer != null) {
1327                         return mixer;
1328                     }
1329                 }
1330 
1331             }
1332         }
1333 
1334         /* Provider class not specified or
1335            provider class cannot be found, or
1336            provider class and instance specified and instance cannot be found or is not appropriate */
1337         if (instanceName != null) {
1338             mixer = getNamedMixer(instanceName, providers, info);
1339             if (mixer != null) {
1340                 return mixer;
1341             }
1342         }
1343 
1344 
1345         /* No default are specified, or if something is specified, everything
1346            failed. */
1347         return null;
1348     }
1349 
1350     /**
1351      * Return a MixerProvider of a given class from the list of MixerProviders.
1352      * This method never requires the returned Mixer to do mixing.
1353      *
1354      * @param  providerClassName The class name of the provider to be returned
1355      * @param  providers The list of MixerProviders that is searched
1356      * @return A MixerProvider of the requested class, or null if none is found
1357      */
1358     private static MixerProvider getNamedProvider(String providerClassName,
1359                                                   List<MixerProvider> providers) {
1360         for(int i = 0; i < providers.size(); i++) {
1361             MixerProvider provider = providers.get(i);
1362             if (provider.getClass().getName().equals(providerClassName)) {
1363                 return provider;
1364             }
1365         }
1366         return null;
1367     }
1368 
1369     /**
1370      * Return a Mixer with a given name from a given MixerProvider. This method
1371      * never requires the returned Mixer to do mixing.
1372      *
1373      * @param  mixerName The name of the Mixer to be returned
1374      * @param  provider The MixerProvider to check for Mixers
1375      * @param  info The type of line the returned Mixer is required to support
1376      * @return A Mixer matching the requirements, or null if none is found
1377      */
1378     private static Mixer getNamedMixer(String mixerName,
1379                                        MixerProvider provider,
1380                                        Line.Info info) {
1381         Mixer.Info[] infos = provider.getMixerInfo();
1382         for (int i = 0; i < infos.length; i++) {
1383             if (infos[i].getName().equals(mixerName)) {
1384                 Mixer mixer = provider.getMixer(infos[i]);
1385                 if (isAppropriateMixer(mixer, info, false)) {
1386                     return mixer;
1387                 }
1388             }
1389         }
1390         return null;
1391     }
1392 
1393     /**
1394      * From a List of MixerProviders, return a Mixer with a given name. This
1395      * method never requires the returned Mixer to do mixing.
1396      *
1397      * @param  mixerName The name of the Mixer to be returned
1398      * @param  providers The List of MixerProviders to check for Mixers
1399      * @param  info The type of line the returned Mixer is required to support
1400      * @return A Mixer matching the requirements, or null if none is found
1401      */
1402     private static Mixer getNamedMixer(String mixerName,
1403                                        List<MixerProvider> providers,
1404                                        Line.Info info) {
1405         for(int i = 0; i < providers.size(); i++) {
1406             MixerProvider provider = providers.get(i);
1407             Mixer mixer = getNamedMixer(mixerName, provider, info);
1408             if (mixer != null) {
1409                 return mixer;
1410             }
1411         }
1412         return null;
1413     }
1414 
1415     /**
1416      * From a given MixerProvider, return the first appropriate Mixer.
1417      *
1418      * @param  provider The MixerProvider to check for Mixers
1419      * @param  info The type of line the returned Mixer is required to support
1420      * @param  isMixingRequired If true, only Mixers that support mixing are
1421      *         returned for line types of SourceDataLine and Clip
1422      * @return A Mixer that is considered appropriate, or null if none is found
1423      */
1424     private static Mixer getFirstMixer(MixerProvider provider,
1425                                        Line.Info info,
1426                                        boolean isMixingRequired) {
1427         Mixer.Info[] infos = provider.getMixerInfo();
1428         for (int j = 0; j < infos.length; j++) {
1429             Mixer mixer = provider.getMixer(infos[j]);
1430             if (isAppropriateMixer(mixer, info, isMixingRequired)) {
1431                 return mixer;
1432             }
1433         }
1434         return null;
1435     }
1436 
1437     /**
1438      * Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
1439      * support the given line type. If isMixingRequired is true and the line
1440      * type is an output one (SourceDataLine, Clip), the mixer is appropriate if
1441      * it supports at least 2 (concurrent) lines of the given type.
1442      *
1443      * @return {@code true} if the mixer is considered appropriate according to
1444      *         the rules given above, {@code false} otherwise
1445      */
1446     private static boolean isAppropriateMixer(Mixer mixer,
1447                                               Line.Info lineInfo,
1448                                               boolean isMixingRequired) {
1449         if (! mixer.isLineSupported(lineInfo)) {
1450             return false;
1451         }
1452         Class<?> lineClass = lineInfo.getLineClass();
1453         if (isMixingRequired
1454             && (SourceDataLine.class.isAssignableFrom(lineClass) ||
1455                 Clip.class.isAssignableFrom(lineClass))) {
1456             int maxLines = mixer.getMaxLines(lineInfo);
1457             return ((maxLines == NOT_SPECIFIED) || (maxLines > 1));
1458         }
1459         return true;
1460     }
1461 
1462     /**
1463      * Like getMixerInfo, but return List.
1464      */
1465     private static List<Mixer.Info> getMixerInfoList() {
1466         List<MixerProvider> providers = getMixerProviders();
1467         return getMixerInfoList(providers);
1468     }
1469 
1470     /**
1471      * Like getMixerInfo, but return List.
1472      */
1473     private static List<Mixer.Info> getMixerInfoList(List<MixerProvider> providers) {
1474         List<Mixer.Info> infos = new ArrayList<>();
1475 
1476         Mixer.Info[] someInfos; // per-mixer
1477         Mixer.Info[] allInfos;  // for all mixers
1478 
1479         for(int i = 0; i < providers.size(); i++ ) {
1480             someInfos = providers.get(i).getMixerInfo();
1481 
1482             for (int j = 0; j < someInfos.length; j++) {
1483                 infos.add(someInfos[j]);
1484             }
1485         }
1486 
1487         return infos;
1488     }
1489 
1490     /**
1491      * Obtains the set of services currently installed on the system using the
1492      * SPI mechanism in 1.3.
1493      *
1494      * @return a List of instances of providers for the requested service. If no
1495      *         providers are available, a vector of length 0 will be returned.
1496      */
1497     private static List<?> getProviders(Class<?> providerClass) {
1498         return JDK13Services.getProviders(providerClass);
1499     }
1500 }