< prev index next >
src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java
Print this page
*** 23,33 ****
* questions.
*/
package javax.sound.sampled;
- import java.io.EOFException;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URL;
--- 23,32 ----
*** 74,109 ****
*
* <table class="striped">
* <caption>Audio System Property Keys</caption>
* <thead>
* <tr>
! * <th>Property Key</th>
! * <th>Interface</th>
! * <th>Affected Method(s)</th>
! * </tr>
* </thead>
* <tbody>
* <tr>
! * <td>{@code javax.sound.sampled.Clip}</td>
! * <td>{@link Clip}</td>
! * <td>{@link #getLine}, {@link #getClip}</td>
! * </tr>
* <tr>
! * <td>{@code javax.sound.sampled.Port}</td>
! * <td>{@link Port}</td>
! * <td>{@link #getLine}</td>
! * </tr>
* <tr>
! * <td>{@code javax.sound.sampled.SourceDataLine}</td>
! * <td>{@link SourceDataLine}</td>
! * <td>{@link #getLine}, {@link #getSourceDataLine}</td>
! * </tr>
* <tr>
! * <td>{@code javax.sound.sampled.TargetDataLine}</td>
! * <td>{@link TargetDataLine}</td>
! * <td>{@link #getLine}, {@link #getTargetDataLine}</td>
! * </tr>
* </tbody>
* </table>
*
* The property value consists of the provider class name and the mixer name,
* separated by the hash mark ("#"). The provider class name is the
--- 73,103 ----
*
* <table class="striped">
* <caption>Audio System Property Keys</caption>
* <thead>
* <tr>
! * <th>Property Key
! * <th>Interface
! * <th>Affected Method(s)
* </thead>
* <tbody>
* <tr>
! * <td>{@code javax.sound.sampled.Clip}
! * <td>{@link Clip}
! * <td>{@link #getLine}, {@link #getClip}
* <tr>
! * <td>{@code javax.sound.sampled.Port}
! * <td>{@link Port}
! * <td>{@link #getLine}
* <tr>
! * <td>{@code javax.sound.sampled.SourceDataLine}
! * <td>{@link SourceDataLine}
! * <td>{@link #getLine}, {@link #getSourceDataLine}
* <tr>
! * <td>{@code javax.sound.sampled.TargetDataLine}
! * <td>{@link TargetDataLine}
! * <td>{@link #getLine}, {@link #getTargetDataLine}
* </tbody>
* </table>
*
* The property value consists of the provider class name and the mixer name,
* separated by the hash mark ("#"). The provider class name is the
*** 123,146 ****
* objects is searched: the first one with a matching name, and whose
* {@code Mixer} provides the respective line interface, will be returned. If no
* matching {@code Mixer.Info} object is found, or the mixer name is not
* specified, the first mixer from the resulting list, which provides the
* respective line interface, will be returned.
! *
* For example, the property {@code javax.sound.sampled.Clip} with a value
! * {@code "com.sun.media.sound.MixerProvider#SunClip"}
! * will have the following consequences when {@code getLine} is called
! * requesting a {@code Clip} instance: if the class
! * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
! * mixer providers, the first {@code Clip} from the first mixer with name
! * {@code "SunClip"} will be returned. If it cannot be found, the
! * first {@code Clip} from the first mixer of the specified provider will be
* returned, regardless of name. If there is none, the first {@code Clip} from
! * the first {@code Mixer} with name {@code "SunClip"} in the list of
! * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not
! * found, the first {@code Clip} of the first {@code Mixer} that can be found in
! * the list of all mixers is returned. If that fails, too, an
* {@code IllegalArgumentException} is thrown.
*
* @author Kara Kytle
* @author Florian Bomers
* @author Matthias Pfisterer
--- 117,139 ----
* objects is searched: the first one with a matching name, and whose
* {@code Mixer} provides the respective line interface, will be returned. If no
* matching {@code Mixer.Info} object is found, or the mixer name is not
* specified, the first mixer from the resulting list, which provides the
* respective line interface, will be returned.
! * <p>
* For example, the property {@code javax.sound.sampled.Clip} with a value
! * {@code "com.sun.media.sound.MixerProvider#SunClip"} will have the following
! * consequences when {@code getLine} is called requesting a {@code Clip}
! * instance: if the class {@code com.sun.media.sound.MixerProvider} exists in
! * the list of installed mixer providers, the first {@code Clip} from the first
! * mixer with name {@code "SunClip"} will be returned. If it cannot be found,
! * the first {@code Clip} from the first mixer of the specified provider will be
* returned, regardless of name. If there is none, the first {@code Clip} from
! * the first {@code Mixer} with name {@code "SunClip"} in the list of all mixers
! * (as returned by {@code getMixerInfo}) will be returned, or, if not found, the
! * first {@code Clip} of the first {@code Mixer} that can be found in the list
! * of all mixers is returned. If that fails, too, an
* {@code IllegalArgumentException} is thrown.
*
* @author Kara Kytle
* @author Florian Bomers
* @author Matthias Pfisterer
*** 477,487 ****
* {@code getLine} internally.
*
* @param mixerInfo a {@code Mixer.Info} object representing the desired
* mixer, or {@code null} for the system default mixer
* @return a clip object from the specified mixer
- *
* @throws LineUnavailableException if a clip is not available from this
* mixer due to resource restrictions
* @throws SecurityException if a clip is not available from this mixer due
* to security restrictions
* @throws IllegalArgumentException if the system does not support at least
--- 470,479 ----
*** 668,680 ****
* stream with the specified encoding using the set of installed format
* converters.
*
* @param sourceEncoding the encoding for which conversion support is
* queried
! * @return array of encodings. If {@code sourceEncoding}is not supported, an
! * array of length 0 is returned. Otherwise, the array will have a
! * length of at least 1, representing {@code sourceEncoding}
* (no conversion).
* @throws NullPointerException if {@code sourceEncoding} is {@code null}
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
Objects.requireNonNull(sourceEncoding);
--- 660,672 ----
* stream with the specified encoding using the set of installed format
* converters.
*
* @param sourceEncoding the encoding for which conversion support is
* queried
! * @return array of encodings. If {@code sourceEncoding} is not supported,
! * an array of length 0 is returned. Otherwise, the array will have
! * a length of at least 1, representing {@code sourceEncoding}
* (no conversion).
* @throws NullPointerException if {@code sourceEncoding} is {@code null}
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
Objects.requireNonNull(sourceEncoding);
*** 933,951 ****
}
throw new UnsupportedAudioFileException("Stream of unsupported format");
}
/**
! * Obtains the audio file format of the specified URL. The URL must point to
! * valid audio file data.
*
! * @param url the URL from which file format information should be
* extracted
* @return an {@code AudioFileFormat} object describing the audio file
* format
! * @throws UnsupportedAudioFileException if the URL does not point to valid
! * audio file data recognized by the system
* @throws IOException if an input/output exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
public static AudioFileFormat getAudioFileFormat(final URL url)
throws UnsupportedAudioFileException, IOException {
--- 925,943 ----
}
throw new UnsupportedAudioFileException("Stream of unsupported format");
}
/**
! * Obtains the audio file format of the specified {@code URL}. The
! * {@code URL} must point to valid audio file data.
*
! * @param url the {@code URL} from which file format information should be
* extracted
* @return an {@code AudioFileFormat} object describing the audio file
* format
! * @throws UnsupportedAudioFileException if the {@code URL} does not point
! * to valid audio file data recognized by the system
* @throws IOException if an input/output exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
public static AudioFileFormat getAudioFileFormat(final URL url)
throws UnsupportedAudioFileException, IOException {
*** 1019,1037 ****
}
throw new UnsupportedAudioFileException("Stream of unsupported format");
}
/**
! * Obtains an audio input stream from the URL provided. The URL must point
! * to valid audio file data.
*
! * @param url the URL for which the {@code AudioInputStream} should be
! * constructed
* @return an {@code AudioInputStream} object based on the audio file data
! * pointed to by the URL
! * @throws UnsupportedAudioFileException if the URL does not point to valid
! * audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
public static AudioInputStream getAudioInputStream(final URL url)
throws UnsupportedAudioFileException, IOException {
--- 1011,1029 ----
}
throw new UnsupportedAudioFileException("Stream of unsupported format");
}
/**
! * Obtains an audio input stream from the {@code URL} provided. The
! * {@code URL} must point to valid audio file data.
*
! * @param url the {@code URL} for which the {@code AudioInputStream} should
! * be constructed
* @return an {@code AudioInputStream} object based on the audio file data
! * pointed to by the {@code URL}
! * @throws UnsupportedAudioFileException if the {@code URL} does not point
! * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
public static AudioInputStream getAudioInputStream(final URL url)
throws UnsupportedAudioFileException, IOException {
*** 1119,1130 ****
/**
* Obtains the file types that the system can write from the audio input
* stream specified.
*
! * @param stream the audio input stream for which audio file type
! * support is queried
* @return array of file types. If no file types are supported, an array of
* length 0 is returned.
* @throws NullPointerException if {@code stream} is {@code null}
*/
public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) {
--- 1111,1122 ----
/**
* Obtains the file types that the system can write from the audio input
* stream specified.
*
! * @param stream the audio input stream for which audio file type support
! * is queried
* @return array of file types. If no file types are supported, an array of
* length 0 is returned.
* @throws NullPointerException if {@code stream} is {@code null}
*/
public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) {
*** 1173,1184 ****
/**
* Writes a stream of bytes representing an audio file of the specified file
* type to the output stream provided. Some file types require that the
* length be written into the file header; such files cannot be written from
* start to finish unless the length is known in advance. An attempt to
! * write a file of such a type will fail with an IOException if the length
! * in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
*
* @param stream the audio input stream containing audio data to be written
* to the file
* @param fileType the kind of audio file to write
* @param out the stream to which the file data should be written
--- 1165,1176 ----
/**
* Writes a stream of bytes representing an audio file of the specified file
* type to the output stream provided. Some file types require that the
* length be written into the file header; such files cannot be written from
* start to finish unless the length is known in advance. An attempt to
! * write a file of such a type will fail with an {@code IOException} if the
! * length in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
*
* @param stream the audio input stream containing audio data to be written
* to the file
* @param fileType the kind of audio file to write
* @param out the stream to which the file data should be written
*** 1248,1258 ****
}
// METHODS FOR INTERNAL IMPLEMENTATION USE
/**
! * Obtains the set of MixerProviders on the system.
*/
@SuppressWarnings("unchecked")
private static List<MixerProvider> getMixerProviders() {
return (List<MixerProvider>) getProviders(MixerProvider.class);
}
--- 1240,1252 ----
}
// METHODS FOR INTERNAL IMPLEMENTATION USE
/**
! * Obtains the list of MixerProviders currently installed on the system.
! *
! * @return the list of MixerProviders currently installed on the system
*/
@SuppressWarnings("unchecked")
private static List<MixerProvider> getMixerProviders() {
return (List<MixerProvider>) getProviders(MixerProvider.class);
}
*** 1329,1351 ****
}
}
}
! /* Provider class not specified or
! provider class cannot be found, or
! provider class and instance specified and instance cannot be found or is not appropriate */
if (instanceName != null) {
mixer = getNamedMixer(instanceName, providers, info);
if (mixer != null) {
return mixer;
}
}
! /* No default are specified, or if something is specified, everything
! failed. */
return null;
}
/**
* Return a MixerProvider of a given class from the list of MixerProviders.
--- 1323,1349 ----
}
}
}
! /*
! * Provider class not specified or provider class cannot be found, or
! * provider class and instance specified and instance cannot be found or
! * is not appropriate
! */
if (instanceName != null) {
mixer = getNamedMixer(instanceName, providers, info);
if (mixer != null) {
return mixer;
}
}
! /*
! * No defaults are specified, or if something is specified, everything
! * failed.
! */
return null;
}
/**
* Return a MixerProvider of a given class from the list of MixerProviders.
*** 1434,1447 ****
return null;
}
/**
* Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
! * support the given line type. If isMixingRequired is true and the line
! * type is an output one (SourceDataLine, Clip), the mixer is appropriate if
! * it supports at least 2 (concurrent) lines of the given type.
! *
* @return {@code true} if the mixer is considered appropriate according to
* the rules given above, {@code false} otherwise
*/
private static boolean isAppropriateMixer(Mixer mixer,
Line.Info lineInfo,
--- 1432,1449 ----
return null;
}
/**
* Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
! * support the given line type. If isMixingRequired is {@code true} and the
! * line type is an output one (SourceDataLine, Clip), the mixer is
! * appropriate if it supports at least 2 (concurrent) lines of the given
! * type.
! *
! * @param mixer The mixer to check
! * @param lineInfo The line to check
! * @param isMixingRequired Is the mixing required or not
* @return {@code true} if the mixer is considered appropriate according to
* the rules given above, {@code false} otherwise
*/
private static boolean isAppropriateMixer(Mixer mixer,
Line.Info lineInfo,
*** 1459,1476 ****
--- 1461,1487 ----
return true;
}
/**
* Like getMixerInfo, but return List.
+ *
+ * @return a List of info objects for the currently installed mixers. If no
+ * mixers are available on the system, an empty List is returned.
+ * @see #getMixerInfo()
*/
private static List<Mixer.Info> getMixerInfoList() {
List<MixerProvider> providers = getMixerProviders();
return getMixerInfoList(providers);
}
/**
* Like getMixerInfo, but return List.
+ *
+ * @param providers The list of MixerProviders
+ * @return a List of info objects for the currently installed mixers. If no
+ * mixers are available on the system, an empty List is returned.
+ * @see #getMixerInfo()
*/
private static List<Mixer.Info> getMixerInfoList(List<MixerProvider> providers) {
List<Mixer.Info> infos = new ArrayList<>();
Mixer.Info[] someInfos; // per-mixer
*** 1489,1498 ****
--- 1500,1514 ----
/**
* Obtains the set of services currently installed on the system using the
* SPI mechanism in 1.3.
*
+ * @param providerClass The type of providers requested. This should be one
+ * of AudioFileReader.class, AudioFileWriter.class,
+ * FormatConversionProvider.class, MixerProvider.class,
+ * MidiDeviceProvider.class, MidiFileReader.class,
+ * MidiFileWriter.class or SoundbankReader.class.
* @return a List of instances of providers for the requested service. If no
* providers are available, a vector of length 0 will be returned.
*/
private static List<?> getProviders(Class<?> providerClass) {
return JDK13Services.getProviders(providerClass);
< prev index next >