AudioFileFormat class describes
- * an audio file, including the file type, the file's length in bytes,
- * the length in sample frames of the audio data contained in the file,
- * and the format of the audio data.
+ * An instance of the {@code AudioFileFormat} class describes an audio file,
+ * including the file type, the file's length in bytes, the length in sample
+ * frames of the audio data contained in the file, and the format of the audio
+ * data.
*
- * The {@link AudioSystem} class includes methods for determining the format
- * of an audio file, obtaining an audio input stream from an audio file, and
+ * The {@link AudioSystem} class includes methods for determining the format of
+ * an audio file, obtaining an audio input stream from an audio file, and
* writing an audio file from an audio input stream.
- *
- *
An AudioFileFormat object can
- * include a set of properties. A property is a pair of key and value:
- * the key is of type String, the associated property
- * value is an arbitrary object.
- * Properties specify additional informational
- * meta data (like a author, copyright, or file duration).
- * Properties are optional information, and file reader and file
- * writer implementations are not required to provide or
- * recognize properties.
- *
- *
The following table lists some common properties that should - * be used in implementations: + *
+ * An {@code AudioFileFormat} object can include a set of properties. A property + * is a pair of key and value: the key is of type {@code String}, the associated + * property value is an arbitrary object. Properties specify additional + * informational meta data (like a author, copyright, or file duration). + * Properties are optional information, and file reader and file writer + * implementations are not required to provide or recognize properties. + *
+ * The following table lists some common properties that should be used in + * implementations: * *
| "vbr" | *{@link java.lang.Boolean Boolean} | - *true, if the file is encoded in variable bit
+ * | {@code true}, if the file is encoded in variable bit * rate (VBR) | *
| encoding/conversion quality, 1..100 | *
Vendors of service providers (plugins) are encouraged - * to seek information about other already established - * properties in third party plugins, and follow the same - * conventions. + *
+ * Vendors of service providers (plugins) are encouraged to seek information
+ * about other already established properties in third party plugins, and follow
+ * the same conventions.
*
* @author Kara Kytle
* @author Florian Bomers
@@ -124,16 +127,14 @@
*/
public class AudioFormat {
- // INSTANCE VARIABLES
-
-
/**
* The audio encoding technique used by this format.
*/
protected Encoding encoding;
/**
- * The number of samples played or recorded per second, for sounds that have this format.
+ * The number of samples played or recorded per second, for sounds that have
+ * this format.
*/
protected float sampleRate;
@@ -153,34 +154,37 @@
protected int frameSize;
/**
- * The number of frames played or recorded per second, for sounds that have this format.
+ * The number of frames played or recorded per second, for sounds that have
+ * this format.
*/
protected float frameRate;
/**
- * Indicates whether the audio data is stored in big-endian or little-endian order.
+ * Indicates whether the audio data is stored in big-endian or little-endian
+ * order.
*/
protected boolean bigEndian;
-
- /** The set of properties */
+ /**
+ * The set of properties.
+ */
private HashMap
+ * If the specified property is not defined for a particular file format,
+ * this method returns {@code null}.
*
- * If the specified property is not defined for a
- * particular file format, this method returns
- *
* One ubiquitous type of audio encoding is pulse-code modulation (PCM),
* which is simply a linear (proportional) representation of the sound
- * waveform. With PCM, the number stored in each sample is proportional
- * to the instantaneous amplitude of the sound pressure at that point in
- * time. The numbers may be signed or unsigned integers or floats.
- * Besides PCM, other encodings include mu-law and a-law, which are nonlinear
- * mappings of the sound amplitude that are often used for recording speech.
+ * waveform. With PCM, the number stored in each sample is proportional to
+ * the instantaneous amplitude of the sound pressure at that point in time.
+ * The numbers may be signed or unsigned integers or floats. Besides PCM,
+ * other encodings include mu-law and a-law, which are nonlinear mappings of
+ * the sound amplitude that are often used for recording speech.
*
* You can use a predefined encoding by referring to one of the static
- * objects created by this class, such as PCM_SIGNED or
- * PCM_UNSIGNED. Service providers can create new encodings, such as
- * compressed audio formats, and make
- * these available through the
- * The
- * The This method will always read an integral number of frames.
- * If the length of the array is not an integral number
- * of frames, a maximum of
+ * This method will always read an integral number of frames. If the length
+ * of the array is not an integral number of frames, a maximum of
+ * {@code b.length - (b.length % frameSize)} bytes will be read.
*
- * @param b the buffer into which the data is read
- * @return the total number of bytes read into the buffer, or -1 if there
- * is no more data because the end of the stream has been reached
+ * @param b the buffer into which the data is read
+ * @return the total number of bytes read into the buffer, or -1 if there is
+ * no more data because the end of the stream has been reached
* @throws IOException if an input or output error occurs
* @see #read(byte[], int, int)
* @see #read()
* @see #available
*/
+ @Override
public int read(byte[] b) throws IOException {
return read(b,0,b.length);
}
-
/**
* Reads up to a specified maximum number of bytes of data from the audio
* stream, putting them into the given byte array.
- * This method will always read an integral number of frames.
- * If
+ * This method will always read an integral number of frames. If {@code len}
+ * does not specify an integral number of frames, a maximum of
+ * {@code len - (len % frameSize)} bytes will be read.
*
- * @param b the buffer into which the data is read
- * @param off the offset, from the beginning of array
* The target name is the name of the audio permission (see the table below).
- * The names follow the hierarchical property-naming convention. Also, an asterisk
- * can be used to represent all the audio permissions.
+ * The names follow the hierarchical property-naming convention. Also, an
+ * asterisk can be used to represent all the audio permissions.
*
- * The following table lists the possible
+ *
+ * AudioFormat with the given parameters.
- * The encoding specifies the convention used to represent the data.
- * The other parameters are further explained in the {@link AudioFormat
- * class description}.
- * @param encoding the audio encoding technique
- * @param sampleRate the number of samples per second
- * @param sampleSizeInBits the number of bits in each sample
- * @param channels the number of channels (1 for mono, 2 for stereo, and so on)
- * @param frameSize the number of bytes in each frame
- * @param frameRate the number of frames per second
- * @param bigEndian indicates whether the data for a single sample
- * is stored in big-endian byte order (false
- * means little-endian)
+ * Constructs an {@code AudioFormat} with the given parameters. The encoding
+ * specifies the convention used to represent the data. The other parameters
+ * are further explained in the {@link AudioFormat class description}.
+ *
+ * @param encoding the audio encoding technique
+ * @param sampleRate the number of samples per second
+ * @param sampleSizeInBits the number of bits in each sample
+ * @param channels the number of channels (1 for mono, 2 for stereo,
+ * and so on)
+ * @param frameSize the number of bytes in each frame
+ * @param frameRate the number of frames per second
+ * @param bigEndian indicates whether the data for a single sample is
+ * stored in big-endian byte order ({@code false} means
+ * little-endian)
*/
public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
int channels, int frameSize, float frameRate, boolean bigEndian) {
@@ -195,25 +199,22 @@
this.properties = null;
}
-
/**
- * Constructs an AudioFormat with the given parameters.
- * The encoding specifies the convention used to represent the data.
- * The other parameters are further explained in the {@link AudioFormat
- * class description}.
- * @param encoding the audio encoding technique
- * @param sampleRate the number of samples per second
- * @param sampleSizeInBits the number of bits in each sample
- * @param channels the number of channels (1 for mono, 2 for
- * stereo, and so on)
- * @param frameSize the number of bytes in each frame
- * @param frameRate the number of frames per second
- * @param bigEndian indicates whether the data for a single sample
- * is stored in big-endian byte order
- * (false means little-endian)
- * @param properties a Map<String,Object> object
- * containing format properties
+ * Constructs an {@code AudioFormat} with the given parameters. The encoding
+ * specifies the convention used to represent the data. The other parameters
+ * are further explained in the {@link AudioFormat class description}.
*
+ * @param encoding the audio encoding technique
+ * @param sampleRate the number of samples per second
+ * @param sampleSizeInBits the number of bits in each sample
+ * @param channels the number of channels (1 for mono, 2 for stereo, and so
+ * on)
+ * @param frameSize the number of bytes in each frame
+ * @param frameRate the number of frames per second
+ * @param bigEndian indicates whether the data for a single sample is
+ * stored in big-endian byte order ({@code false} means little-endian)
+ * @param properties a {@code MapAudioFormat with a linear PCM encoding and
- * the given parameters. The frame size is set to the number of bytes
- * required to contain one sample from each channel, and the frame rate
- * is set to the sample rate.
+ * Constructs an {@code AudioFormat} with a linear PCM encoding and the
+ * given parameters. The frame size is set to the number of bytes required
+ * to contain one sample from each channel, and the frame rate is set to the
+ * sample rate.
*
- * @param sampleRate the number of samples per second
- * @param sampleSizeInBits the number of bits in each sample
- * @param channels the number of channels (1 for mono, 2 for stereo, and so on)
- * @param signed indicates whether the data is signed or unsigned
- * @param bigEndian indicates whether the data for a single sample
- * is stored in big-endian byte order (false
- * means little-endian)
+ * @param sampleRate the number of samples per second
+ * @param sampleSizeInBits the number of bits in each sample
+ * @param channels the number of channels (1 for mono, 2 for stereo, and so
+ * on)
+ * @param signed indicates whether the data is signed or unsigned
+ * @param bigEndian indicates whether the data for a single sample is
+ * stored in big-endian byte order ({@code false} means
+ * little-endian)
*/
public AudioFormat(float sampleRate, int sampleSizeInBits,
int channels, boolean signed, boolean bigEndian) {
@@ -269,19 +270,17 @@
}
/**
- * Obtains the sample rate.
- * For compressed formats, the return value is the sample rate of the uncompressed
- * audio data.
- * When this AudioFormat is used for queries (e.g. {@link
- * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
- * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample rate of
- * AudioSystem.NOT_SPECIFIED means that any sample rate is
- * acceptable. AudioSystem.NOT_SPECIFIED is also returned when
- * the sample rate is not defined for this audio format.
- * @return the number of samples per second,
- * or AudioSystem.NOT_SPECIFIED
+ * Obtains the sample rate. For compressed formats, the return value is the
+ * sample rate of the uncompressed audio data. When this AudioFormat is used
+ * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+ * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
+ * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample rate
+ * of {@code AudioSystem.NOT_SPECIFIED} means that any sample rate is
+ * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
+ * sample rate is not defined for this audio format.
*
+ * @return the number of samples per second, or
+ * {@code AudioSystem.NOT_SPECIFIED}
* @see #getFrameRate()
* @see AudioSystem#NOT_SPECIFIED
*/
@@ -291,19 +290,18 @@
}
/**
- * Obtains the size of a sample.
- * For compressed formats, the return value is the sample size of the
- * uncompressed audio data.
- * When this AudioFormat is used for queries (e.g. {@link
- * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
- * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample size of
- * AudioSystem.NOT_SPECIFIED means that any sample size is
- * acceptable. AudioSystem.NOT_SPECIFIED is also returned when
- * the sample size is not defined for this audio format.
- * @return the number of bits in each sample,
- * or AudioSystem.NOT_SPECIFIED
+ * Obtains the size of a sample. For compressed formats, the return value is
+ * the sample size of the uncompressed audio data. When this AudioFormat is
+ * used for queries (e.g. {@link AudioSystem#isConversionSupported(
+ * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
+ * capabilities (e.g.
+ * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample size
+ * of {@code AudioSystem.NOT_SPECIFIED} means that any sample size is
+ * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
+ * sample size is not defined for this audio format.
*
+ * @return the number of bits in each sample, or
+ * {@code AudioSystem.NOT_SPECIFIED}
* @see #getFrameSize()
* @see AudioSystem#NOT_SPECIFIED
*/
@@ -313,16 +311,15 @@
}
/**
- * Obtains the number of channels.
- * When this AudioFormat is used for queries (e.g. {@link
- * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
- * DataLine.Info#getFormats() DataLine.Info.getFormats}), a return value of
- * AudioSystem.NOT_SPECIFIED means that any (positive) number of channels is
- * acceptable.
- * @return The number of channels (1 for mono, 2 for stereo, etc.),
- * or AudioSystem.NOT_SPECIFIED
+ * Obtains the number of channels. When this AudioFormat is used for queries
+ * (e.g. {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+ * AudioSystem.isConversionSupported}) or capabilities (e.g.
+ * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a return
+ * value of {@code AudioSystem.NOT_SPECIFIED} means that any (positive)
+ * number of channels is acceptable.
*
+ * @return The number of channels (1 for mono, 2 for stereo, etc.), or
+ * {@code AudioSystem.NOT_SPECIFIED}
* @see AudioSystem#NOT_SPECIFIED
*/
public int getChannels() {
@@ -331,17 +328,16 @@
}
/**
- * Obtains the frame size in bytes.
- * When this AudioFormat is used for queries (e.g. {@link
- * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
- * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame size of
- * AudioSystem.NOT_SPECIFIED means that any frame size is
- * acceptable. AudioSystem.NOT_SPECIFIED is also returned when
- * the frame size is not defined for this audio format.
- * @return the number of bytes per frame,
- * or AudioSystem.NOT_SPECIFIED
+ * Obtains the frame size in bytes. When this AudioFormat is used for
+ * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+ * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
+ * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame size
+ * of {@code AudioSystem.NOT_SPECIFIED} means that any frame size is
+ * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
+ * frame size is not defined for this audio format.
*
+ * @return the number of bytes per frame, or
+ * {@code AudioSystem.NOT_SPECIFIED}
* @see #getSampleSizeInBits()
* @see AudioSystem#NOT_SPECIFIED
*/
@@ -351,17 +347,17 @@
}
/**
- * Obtains the frame rate in frames per second.
- * When this AudioFormat is used for queries (e.g. {@link
- * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
- * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame rate of
- * AudioSystem.NOT_SPECIFIED means that any frame rate is
- * acceptable. AudioSystem.NOT_SPECIFIED is also returned when
- * the frame rate is not defined for this audio format.
- * @return the number of frames per second,
- * or AudioSystem.NOT_SPECIFIED
+ * Obtains the frame rate in frames per second. When this AudioFormat is
+ * used for queries (e.g. {@link AudioSystem#isConversionSupported(
+ * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
+ * capabilities (e.g.
+ * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame rate
+ * of {@code AudioSystem.NOT_SPECIFIED} means that any frame rate is
+ * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
+ * frame rate is not defined for this audio format.
*
+ * @return the number of frames per second, or
+ * {@code AudioSystem.NOT_SPECIFIED}
* @see #getSampleRate()
* @see AudioSystem#NOT_SPECIFIED
*/
@@ -370,29 +366,25 @@
return frameRate;
}
-
/**
* Indicates whether the audio data is stored in big-endian or little-endian
- * byte order. If the sample size is not more than one byte, the return value is
- * irrelevant.
- * @return true if the data is stored in big-endian byte order,
- * false if little-endian
+ * byte order. If the sample size is not more than one byte, the return
+ * value is irrelevant.
+ *
+ * @return {@code true} if the data is stored in big-endian byte order,
+ * {@code false} if little-endian
*/
public boolean isBigEndian() {
return bigEndian;
}
-
/**
- * Obtain an unmodifiable map of properties.
- * The concept of properties is further explained in
- * the {@link AudioFileFormat class description}.
+ * Obtain an unmodifiable map of properties. The concept of properties is
+ * further explained in the {@link AudioFileFormat class description}.
*
- * @return a Map<String,Object> object containing
- * all properties. If no properties are recognized, an empty map is
- * returned.
- *
+ * @return a {@code Mapnull.
- *
- * @param key the key of the desired property
- * @return the value of the property with the specified key,
- * or null if the property does not exist.
- *
+ * @param key the key of the desired property
+ * @return the value of the property with the specified key, or {@code null}
+ * if the property does not exist
* @see #properties()
* @since 1.5
*/
@@ -430,21 +418,18 @@
return properties.get(key);
}
-
/**
- * Indicates whether this format matches the one specified.
- * To match, two formats must have the same encoding,
- * and consistent values of the number of channels, sample rate, sample size,
- * frame rate, and frame size.
- * The values of the property are consistent if they are equal
- * or the specified format has the property value
- * {@code AudioSystem.NOT_SPECIFIED}.
- * The byte order (big-endian or little-endian) must be the same
- * if the sample size is greater than one byte.
+ * Indicates whether this format matches the one specified. To match, two
+ * formats must have the same encoding, and consistent values of the number
+ * of channels, sample rate, sample size, frame rate, and frame size. The
+ * values of the property are consistent if they are equal or the specified
+ * format has the property value {@code AudioSystem.NOT_SPECIFIED}. The byte
+ * order (big-endian or little-endian) must be the same if the sample size
+ * is greater than one byte.
*
- * @param format format to test for match
+ * @param format format to test for match
* @return {@code true} if this format matches the one specified,
- * {@code false} otherwise.
+ * {@code false} otherwise
*/
public boolean matches(AudioFormat format) {
if (format.getEncoding().equals(getEncoding())
@@ -465,14 +450,14 @@
return false;
}
-
/**
- * Returns a string that describes the format, such as:
- * "PCM SIGNED 22050 Hz 16 bit mono big-endian". The contents of the string
- * may vary between implementations of Java Sound.
+ * Returns a string that describes the format, such as: "PCM SIGNED 22050 Hz
+ * 16 bit mono big-endian". The contents of the string may vary between
+ * implementations of Java Sound.
*
* @return a string that describes the format parameters
*/
+ @Override
public String toString() {
String sEncoding = "";
if (getEncoding() != null) {
@@ -546,42 +531,36 @@
}
/**
- * The Encoding class names the specific type of data representation
- * used for an audio stream. The encoding includes aspects of the
- * sound format other than the number of channels, sample rate, sample size,
- * frame rate, frame size, and byte order.
+ * The {@code Encoding} class names the specific type of data representation
+ * used for an audio stream. The encoding includes aspects of the sound
+ * format other than the number of channels, sample rate, sample size, frame
+ * rate, frame size, and byte order.
* {@link AudioSystem} class.
+ * objects created by this class, such as PCM_SIGNED or PCM_UNSIGNED.
+ * Service providers can create new encodings, such as compressed audio
+ * formats, and make these available through the {@link AudioSystem} class.
* Encoding class is static, so that all
- * AudioFormat objects that have the same encoding will refer
- * to the same object (rather than different instances of the same class).
- * This allows matches to be made by checking that two format's encodings
- * are equal.
+ * The {@code Encoding} class is static, so that all {@code AudioFormat}
+ * objects that have the same encoding will refer to the same object (rather
+ * than different instances of the same class). This allows matches to be
+ * made by checking that two format's encodings are equal.
*
+ * @author Kara Kytle
* @see AudioFormat
* @see javax.sound.sampled.spi.FormatConversionProvider
- *
- * @author Kara Kytle
* @since 1.3
*/
public static class Encoding {
-
- // ENCODING DEFINES
-
/**
* Specifies signed, linear PCM data.
*/
@@ -609,31 +588,24 @@
*/
public static final Encoding ALAW = new Encoding("ALAW");
-
- // INSTANCE VARIABLES
-
/**
* Encoding name.
*/
private String name;
-
- // CONSTRUCTOR
-
/**
* Constructs a new encoding.
- * @param name the name of the new type of encoding
+ *
+ * @param name the name of the new type of encoding
*/
public Encoding(String name) {
this.name = name;
}
-
- // METHODS
-
/**
- * Finalizes the equals method
+ * Finalizes the equals method.
*/
+ @Override
public final boolean equals(Object obj) {
if (toString() == null) {
return (obj != null) && (obj.toString() == null);
@@ -645,8 +617,9 @@
}
/**
- * Finalizes the hashCode method
+ * Finalizes the hashCode method.
*/
+ @Override
public final int hashCode() {
if (toString() == null) {
return 0;
@@ -655,16 +628,17 @@
}
/**
- * Provides the String representation of the encoding. This String is
- * the same name that was passed to the constructor. For the predefined encodings, the name
- * is similar to the encoding's variable (field) name. For example, PCM_SIGNED.toString() returns
- * the name "pcm_signed".
+ * Provides the {@code String} representation of the encoding. This
+ * {@code String} is the same name that was passed to the constructor.
+ * For the predefined encodings, the name is similar to the encoding's
+ * variable (field) name. For example, {@code PCM_SIGNED.toString()}
+ * returns the name "pcm_signed".
*
* @return the encoding name
*/
+ @Override
public final String toString() {
return name;
}
-
- } // class Encoding
+ }
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/AudioInputStream.java
--- a/jdk/src/share/classes/javax/sound/sampled/AudioInputStream.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioInputStream.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,27 +25,24 @@
package javax.sound.sampled;
+import java.io.IOException;
import java.io.InputStream;
-import java.io.PushbackInputStream;
-import java.io.IOException;
/**
* An audio input stream is an input stream with a specified audio format and
- * length. The length is expressed in sample frames, not bytes.
- * Several methods are provided for reading a certain number of bytes from
- * the stream, or an unspecified number of bytes.
- * The audio input stream keeps track of the last byte that was read.
- * You can skip over an arbitrary number of bytes to get to a later position
- * for reading. An audio input stream may support marks. When you set a mark,
- * the current position is remembered so that you can return to it later.
+ * length. The length is expressed in sample frames, not bytes. Several methods
+ * are provided for reading a certain number of bytes from the stream, or an
+ * unspecified number of bytes. The audio input stream keeps track of the last
+ * byte that was read. You can skip over an arbitrary number of bytes to get to
+ * a later position for reading. An audio input stream may support marks. When
+ * you set a mark, the current position is remembered so that you can return to
+ * it later.
* AudioSystem class includes many methods that manipulate
- * AudioInputStream objects.
- * For example, the methods let you:
+ * The {@code AudioSystem} class includes many methods that manipulate
+ * {@code AudioInputStream} objects. For example, the methods let you:
*
- *
@@ -53,16 +50,15 @@
* @author David Rivas
* @author Kara Kytle
* @author Florian Bomers
- *
* @see AudioSystem
- * @see Clip#open(AudioInputStream) Clip.open(AudioInputStream)
+ * @see Clip#open(AudioInputStream)
* @since 1.3
*/
public class AudioInputStream extends InputStream {
/**
- * The InputStream from which this AudioInputStream
- * object was constructed.
+ * The {@code InputStream} from which this {@code AudioInputStream} object
+ * was constructed.
*/
private InputStream stream;
@@ -92,35 +88,34 @@
private long markpos;
/**
- * When the underlying stream could only return
- * a non-integral number of frames, store
- * the remainder in a temporary buffer
+ * When the underlying stream could only return a non-integral number of
+ * frames, store the remainder in a temporary buffer.
*/
private byte[] pushBackBuffer = null;
/**
- * number of valid bytes in the pushBackBuffer
+ * number of valid bytes in the pushBackBuffer.
*/
private int pushBackLen = 0;
/**
- * MarkBuffer at mark position
+ * MarkBuffer at mark position.
*/
private byte[] markPushBackBuffer = null;
/**
- * number of valid bytes in the markPushBackBuffer
+ * number of valid bytes in the markPushBackBuffer.
*/
private int markPushBackLen = 0;
-
/**
- * Constructs an audio input stream that has the requested format and length in sample frames,
- * using audio data from the specified input stream.
- * @param stream the stream on which this AudioInputStream
- * object is based
- * @param format the format of this stream's audio data
- * @param length the length in sample frames of the data in this stream
+ * Constructs an audio input stream that has the requested format and length
+ * in sample frames, using audio data from the specified input stream.
+ *
+ * @param stream the stream on which this {@code AudioInputStream} object
+ * is based
+ * @param format the format of this stream's audio data
+ * @param length the length in sample frames of the data in this stream
*/
public AudioInputStream(InputStream stream, AudioFormat format, long length) {
@@ -141,12 +136,12 @@
markpos = 0;
}
-
/**
- * Constructs an audio input stream that reads its data from the target
- * data line indicated. The format of the stream is the same as that of
- * the target data line, and the length is AudioSystem#NOT_SPECIFIED.
- * @param line the target data line from which this stream obtains its data.
+ * Constructs an audio input stream that reads its data from the target data
+ * line indicated. The format of the stream is the same as that of the
+ * target data line, and the length is AudioSystem#NOT_SPECIFIED.
+ *
+ * @param line the target data line from which this stream obtains its data
* @see AudioSystem#NOT_SPECIFIED
*/
public AudioInputStream(TargetDataLine line) {
@@ -164,29 +159,29 @@
markpos = 0;
}
-
/**
* Obtains the audio format of the sound data in this audio input stream.
+ *
* @return an audio format object describing this stream's format
*/
public AudioFormat getFormat() {
return format;
}
-
/**
- * Obtains the length of the stream, expressed in sample frames rather than bytes.
+ * Obtains the length of the stream, expressed in sample frames rather than
+ * bytes.
+ *
* @return the length in sample frames
*/
public long getFrameLength() {
return frameLength;
}
-
/**
- * Reads the next byte of data from the audio input stream. The audio input
- * stream's frame size must be one byte, or an IOException
- * will be thrown.
+ * Reads the next byte of data from the audio input stream. The audio input
+ * stream's frame size must be one byte, or an {@code IOException} will be
+ * thrown.
*
* @return the next byte of data, or -1 if the end of the stream is reached
* @throws IOException if an input or output error occurs
@@ -194,6 +189,7 @@
* @see #read(byte[])
* @see #available
*/
+ @Override
public int read() throws IOException {
if( frameSize != 1 ) {
throw new IOException("cannot read a single byte if frame size > 1");
@@ -208,50 +204,50 @@
return data[0] & 0xFF;
}
-
/**
- * Reads some number of bytes from the audio input stream and stores them into
- * the buffer array b. The number of bytes actually read is
- * returned as an integer. This method blocks until input data is
- * available, the end of the stream is detected, or an exception is thrown.
- * b.length - (b.length % frameSize)
- * bytes will be read.
+ * Reads some number of bytes from the audio input stream and stores them
+ * into the buffer array {@code b}. The number of bytes actually read is
+ * returned as an integer. This method blocks until input data is available,
+ * the end of the stream is detected, or an exception is thrown.
+ * len does not specify an integral number
- * of frames, a maximum of len - (len % frameSize)
- * bytes will be read.
+ * b, at which
- * the data will be written
- * @param len the maximum number of bytes to read
- * @return the total number of bytes read into the buffer, or -1 if there
- * is no more data because the end of the stream has been reached
+ * @param b the buffer into which the data is read
+ * @param off the offset, from the beginning of array {@code b}, at which
+ * the data will be written
+ * @param len the maximum number of bytes to read
+ * @return the total number of bytes read into the buffer, or -1 if there is
+ * no more data because the end of the stream has been reached
* @throws IOException if an input or output error occurs
* @see #read(byte[])
* @see #read()
* @see #skip
* @see #available
*/
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
// make sure we don't read fractions of a frame.
@@ -313,16 +309,17 @@
return bytesRead;
}
-
/**
- * Skips over and discards a specified number of bytes from this
- * audio input stream.
- * @param n the requested number of bytes to be skipped
+ * Skips over and discards a specified number of bytes from this audio input
+ * stream.
+ *
+ * @param n the requested number of bytes to be skipped
* @return the actual number of bytes skipped
* @throws IOException if an input or output error occurs
* @see #read
* @see #available
*/
+ @Override
public long skip(long n) throws IOException {
// make sure not to skip fractional frames
@@ -351,21 +348,23 @@
}
-
/**
- * Returns the maximum number of bytes that can be read (or skipped over) from this
- * audio input stream without blocking. This limit applies only to the next invocation of
- * a read or skip method for this audio input stream; the limit
- * can vary each time these methods are invoked.
- * Depending on the underlying stream,an IOException may be thrown if this
- * stream is closed.
- * @return the number of bytes that can be read from this audio input stream without blocking
+ * Returns the maximum number of bytes that can be read (or skipped over)
+ * from this audio input stream without blocking. This limit applies only
+ * to the next invocation of a {@code read} or {@code skip} method for this
+ * audio input stream; the limit can vary each time these methods are
+ * invoked. Depending on the underlying stream, an IOException may be thrown
+ * if this stream is closed.
+ *
+ * @return the number of bytes that can be read from this audio input stream
+ * without blocking
* @throws IOException if an input or output error occurs
* @see #read(byte[], int, int)
* @see #read(byte[])
* @see #read()
* @see #skip
*/
+ @Override
public int available() throws IOException {
int temp = stream.available();
@@ -378,25 +377,26 @@
}
}
-
/**
- * Closes this audio input stream and releases any system resources associated
- * with the stream.
+ * Closes this audio input stream and releases any system resources
+ * associated with the stream.
+ *
* @throws IOException if an input or output error occurs
*/
+ @Override
public void close() throws IOException {
stream.close();
}
-
/**
* Marks the current position in this audio input stream.
- * @param readlimit the maximum number of bytes that can be read before
- * the mark position becomes invalid.
+ *
+ * @param readlimit the maximum number of bytes that can be read before the
+ * mark position becomes invalid.
* @see #reset
* @see #markSupported
*/
-
+ @Override
public void mark(int readlimit) {
stream.mark(readlimit);
@@ -413,14 +413,15 @@
}
}
-
/**
- * Repositions this audio input stream to the position it had at the time its
- * mark method was last invoked.
- * @throws IOException if an input or output error occurs.
+ * Repositions this audio input stream to the position it had at the time
+ * its {@code mark} method was last invoked.
+ *
+ * @throws IOException if an input or output error occurs
* @see #mark
* @see #markSupported
*/
+ @Override
public void reset() throws IOException {
stream.reset();
@@ -435,21 +436,21 @@
}
}
-
/**
- * Tests whether this audio input stream supports the mark and
- * reset methods.
- * @return true if this stream supports the mark
- * and reset methods; false otherwise
+ * Tests whether this audio input stream supports the {@code mark} and
+ * {@code reset} methods.
+ *
+ * @return {@code true} if this stream supports the {@code mark} and
+ * {@code reset} methods; {@code false} otherwise
* @see #mark
* @see #reset
*/
+ @Override
public boolean markSupported() {
return stream.markSupported();
}
-
/**
* Private inner class that makes a TargetDataLine look like an InputStream.
*/
@@ -460,19 +461,19 @@
*/
TargetDataLine line;
-
TargetDataLineInputStream(TargetDataLine line) {
super();
this.line = line;
}
-
+ @Override
public int available() throws IOException {
return line.available();
}
//$$fb 2001-07-16: added this method to correctly close the underlying TargetDataLine.
// fixes bug 4479984
+ @Override
public void close() throws IOException {
// the line needs to be flushed and stopped to avoid a dead lock...
// Probably related to bugs 4417527, 4334868, 4383457
@@ -483,6 +484,7 @@
line.close();
}
+ @Override
public int read() throws IOException {
byte[] b = new byte[1];
@@ -502,7 +504,7 @@
return value;
}
-
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
try {
return line.read(b, off, len);
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/AudioPermission.java
--- a/jdk/src/share/classes/javax/sound/sampled/AudioPermission.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioPermission.java Wed Jun 04 17:14:56 2014 +0400
@@ -28,18 +28,18 @@
import java.security.BasicPermission;
/**
- * The AudioPermission class represents access rights to the audio
- * system resources. An AudioPermission contains a target name
- * but no actions list; you either have the named permission or you don't.
+ * The {@code AudioPermission} class represents access rights to the audio
+ * system resources. An {@code AudioPermission} contains a target name but no
+ * actions list; you either have the named permission or you don't.
* AudioPermission target names.
- * For each name, the table provides a description of exactly what that permission
- * allows, as well as a discussion of the risks of granting code the permission.
- *
+ * The following table lists the possible {@code AudioPermission} target names.
+ * For each name, the table provides a description of exactly what that
+ * permission allows, as well as a discussion of the risks of granting code the
+ * permission.
*
*
*
- *
@@ -57,7 +57,7 @@
* applications because the audio from one line may be mixed with other audio
* being played on the system, or because manipulation of a mixer affects the
* audio for all lines using that mixer.
- *
+ *
*
*
*
- *record
@@ -68,42 +68,40 @@
* applications because manipulation of a mixer affects the audio for all lines
* using that mixer.
* This permission can enable an applet or application to eavesdrop on a user.
- *
AudioPermission object that has the specified
- * symbolic name, such as "play" or "record". An asterisk can be used to indicate
- * all audio permissions.
- * @param name the name of the new AudioPermission
+ * Creates a new {@code AudioPermission} object that has the specified
+ * symbolic name, such as "play" or "record". An asterisk can be used to
+ * indicate all audio permissions.
*
- * @throws NullPointerException if name is null.
- * @throws IllegalArgumentException if name is empty.
+ * @param name the name of the new {@code AudioPermission}
+ * @throws NullPointerException if {@code name} is {@code null}
+ * @throws IllegalArgumentException if {@code name} is empty
*/
- public AudioPermission(String name) {
-
+ public AudioPermission(final String name) {
super(name);
}
/**
- * Creates a new AudioPermission object that has the specified
- * symbolic name, such as "play" or "record". The actions
- * parameter is currently unused and should be null.
- * @param name the name of the new AudioPermission
- * @param actions (unused; should be null)
+ * Creates a new {@code AudioPermission} object that has the specified
+ * symbolic name, such as "play" or "record". The {@code actions} parameter
+ * is currently unused and should be {@code null}.
*
- * @throws NullPointerException if name is null.
- * @throws IllegalArgumentException if name is empty.
+ * @param name the name of the new {@code AudioPermission}
+ * @param actions (unused; should be {@code null})
+ * @throws NullPointerException if {@code name} is {@code null}
+ * @throws IllegalArgumentException if {@code name} is empty
*/
- public AudioPermission(String name, String actions) {
-
+ public AudioPermission(final String name, final String actions) {
super(name, actions);
}
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/AudioSystem.java
--- a/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Wed Jun 04 17:14:56 2014 +0400
@@ -50,29 +50,24 @@
/**
- * The AudioSystem class acts as the entry point to the
- * sampled-audio system resources. This class lets you query and
- * access the mixers that are installed on the system.
- * AudioSystem includes a number of
- * methods for converting audio data between different formats, and for
- * translating between audio files and streams. It also provides a method
- * for obtaining a {@link Line} directly from the
- * AudioSystem without dealing explicitly
+ * The {@code AudioSystem} class acts as the entry point to the sampled-audio
+ * system resources. This class lets you query and access the mixers that are
+ * installed on the system. {@code AudioSystem} includes a number of methods for
+ * converting audio data between different formats, and for translating between
+ * audio files and streams. It also provides a method for obtaining a
+ * {@link Line} directly from the {@code AudioSystem} without dealing explicitly
* with mixers.
- *
- * Properties can be used to specify the default mixer
- * for specific line types.
- * Both system properties and a properties file are considered.
- * The sound.properties properties file is read from
- * an implementation-specific location (typically it is the lib
- * directory in the Java installation directory).
- * If a property exists both as a system property and in the
- * properties file, the system property takes precedence. If none is
- * specified, a suitable default is chosen among the available devices.
- * The syntax of the properties file is specified in
- * {@link java.util.Properties#load(InputStream) Properties.load}. The
- * following table lists the available property keys and which methods
- * consider them:
+ *
+ * Properties can be used to specify the default mixer for specific line types. + * Both system properties and a properties file are considered. The + * {@code sound.properties} properties file is read from an + * implementation-specific location (typically it is the {@code lib} directory + * in the Java installation directory). If a property exists both as a system + * property and in the properties file, the system property takes precedence. + * If none is specified, a suitable default is chosen among the available + * devices. The syntax of the properties file is specified in + * {@link java.util.Properties#load(InputStream) Properties.load}. The following + * table lists the available property keys and which methods consider them: * *
| Affected Method(s) | * *|||
|---|---|---|---|
javax.sound.sampled.Clip |
+ * {@code javax.sound.sampled.Clip} | *{@link Clip} | *{@link #getLine}, {@link #getClip} | *
javax.sound.sampled.Port |
+ * {@code javax.sound.sampled.Port} | *{@link Port} | *{@link #getLine} | *
javax.sound.sampled.SourceDataLine |
+ * {@code javax.sound.sampled.SourceDataLine} | *{@link SourceDataLine} | *{@link #getLine}, {@link #getSourceDataLine} | *
javax.sound.sampled.TargetDataLine |
+ * {@code javax.sound.sampled.TargetDataLine} | *{@link TargetDataLine} | *{@link #getLine}, {@link #getTargetDataLine} | *
String returned by the getName
- * method of Mixer.Info.
- * Either the class name, or the mixer name may be omitted.
- * If only the class name is specified, the trailing hash mark
- * is optional.
- *
- * If the provider class is specified, and it can be
- * successfully retrieved from the installed providers, the list of
- * Mixer.Info objects is retrieved
- * from the provider. Otherwise, or when these mixers
- * do not provide a subsequent match, the list is retrieved
- * from {@link #getMixerInfo} to contain
- * all available Mixer.Info objects.
- *
- *
If a mixer name is specified, the resulting list of
- * Mixer.Info objects is searched:
- * the first one with a matching name, and whose
- * Mixer provides the
+ * The property value consists of the provider class name and the mixer name,
+ * separated by the hash mark ("#"). The provider class name is the
+ * fully-qualified name of a concrete
+ * {@link javax.sound.sampled.spi.MixerProvider mixer provider} class. The mixer
+ * name is matched against the {@code String} returned by the {@code getName}
+ * method of {@code Mixer.Info}. Either the class name, or the mixer name may be
+ * omitted. If only the class name is specified, the trailing hash mark is
+ * optional.
+ *
+ * If the provider class is specified, and it can be successfully retrieved from + * the installed providers, the list of {@code Mixer.Info} objects is retrieved + * from the provider. Otherwise, or when these mixers do not provide a + * subsequent match, the list is retrieved from {@link #getMixerInfo} to contain + * all available {@code Mixer.Info} objects. + *
+ * If a mixer name is specified, the resulting list of {@code Mixer.Info}
+ * 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.
- * If no matching 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 javax.sound.sampled.Clip
- * with a value
- * "com.sun.media.sound.MixerProvider#SunClip"
- * will have the following consequences when
- * getLine is called requesting a Clip
- * instance:
- * if the class com.sun.media.sound.MixerProvider exists
- * in the list of installed mixer providers,
- * the first Clip from the first mixer with name
- * "SunClip" will be returned. If it cannot
- * be found, the first Clip from the first mixer
- * of the specified provider will be returned, regardless of name.
- * If there is none, the first Clip from the first
- * Mixer with name
- * "SunClip" in the list of all mixers
- * (as returned by getMixerInfo) will be returned,
- * or, if not found, the first Clip of the first
- * Mixerthat can be found in the list of all
- * mixers is returned.
- * If that fails, too, an IllegalArgumentException
- * is thrown.
+ * 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
* @author Kevin P. Smith
- *
* @see AudioFormat
* @see AudioInputStream
* @see Mixer
@@ -170,13 +149,12 @@
public class AudioSystem {
/**
- * An integer that stands for an unknown numeric value.
- * This value is appropriate only for signed quantities that do not
- * normally take negative values. Examples include file sizes, frame
- * sizes, buffer sizes, and sample rates.
- * A number of Java Sound constructors accept
- * a value of NOT_SPECIFIED for such parameters. Other
- * methods may also accept or return this value, as documented.
+ * An integer that stands for an unknown numeric value. This value is
+ * appropriate only for signed quantities that do not normally take negative
+ * values. Examples include file sizes, frame sizes, buffer sizes, and
+ * sample rates. A number of Java Sound constructors accept a value of
+ * {@code NOT_SPECIFIED} for such parameters. Other methods may also accept
+ * or return this value, as documented.
*/
public static final int NOT_SPECIFIED = -1;
@@ -186,12 +164,13 @@
private AudioSystem() {
}
-
/**
- * Obtains an array of mixer info objects that represents
- * the set of audio mixers that are currently installed on the system.
- * @return an array of info objects for the currently installed mixers. If no mixers
- * are available on the system, an array of length 0 is returned.
+ * Obtains an array of mixer info objects that represents the set of audio
+ * mixers that are currently installed on the system.
+ *
+ * @return an array of info objects for the currently installed mixers. If
+ * no mixers are available on the system, an array of length 0 is
+ * returned.
* @see #getMixer
*/
public static Mixer.Info[] getMixerInfo() {
@@ -201,16 +180,16 @@
return allInfos;
}
-
/**
* Obtains the requested audio mixer.
- * @param info a Mixer.Info object representing the desired
- * mixer, or null for the system default mixer
+ *
+ * @param info a {@code Mixer.Info} object representing the desired mixer,
+ * or {@code null} for the system default mixer
* @return the requested mixer
- * @throws SecurityException if the requested mixer
- * is unavailable because of security restrictions
- * @throws IllegalArgumentException if the info object does not represent
- * a mixer installed on the system
+ * @throws SecurityException if the requested mixer is unavailable because
+ * of security restrictions
+ * @throws IllegalArgumentException if the info object does not represent a
+ * mixer installed on the system
* @see #getMixerInfo
*/
public static Mixer getMixer(Mixer.Info info) {
@@ -259,17 +238,17 @@
+ (info!=null?info.toString():"null"));
}
+ //$$fb 2002-11-26: fix for 4757930: DOC: AudioSystem.getTarget/SourceLineInfo() is ambiguous
- //$$fb 2002-11-26: fix for 4757930: DOC: AudioSystem.getTarget/SourceLineInfo() is ambiguous
/**
- * Obtains information about all source lines of a particular type that are supported
- * by the installed mixers.
- * @param info a Line.Info object that specifies the kind of
- * lines about which information is requested
- * @return an array of Line.Info objects describing source lines matching
- * the type requested. If no matching source lines are supported, an array of length 0
- * is returned.
+ * Obtains information about all source lines of a particular type that are
+ * supported by the installed mixers.
*
+ * @param info a {@code Line.Info} object that specifies the kind of lines
+ * about which information is requested
+ * @return an array of {@code Line.Info} objects describing source lines
+ * matching the type requested. If no matching source lines are
+ * supported, an array of length 0 is returned.
* @see Mixer#getSourceLineInfo(Line.Info)
*/
public static Line.Info[] getSourceLineInfo(Line.Info info) {
@@ -300,16 +279,15 @@
return returnedArray;
}
-
/**
- * Obtains information about all target lines of a particular type that are supported
- * by the installed mixers.
- * @param info a Line.Info object that specifies the kind of
- * lines about which information is requested
- * @return an array of Line.Info objects describing target lines matching
- * the type requested. If no matching target lines are supported, an array of length 0
- * is returned.
+ * Obtains information about all target lines of a particular type that are
+ * supported by the installed mixers.
*
+ * @param info a {@code Line.Info} object that specifies the kind of lines
+ * about which information is requested
+ * @return an array of {@code Line.Info} objects describing target lines
+ * matching the type requested. If no matching target lines are
+ * supported, an array of length 0 is returned.
* @see Mixer#getTargetLineInfo(Line.Info)
*/
public static Line.Info[] getTargetLineInfo(Line.Info info) {
@@ -340,15 +318,15 @@
return returnedArray;
}
-
/**
- * Indicates whether the system supports any lines that match
- * the specified Line.Info object. A line is supported if
- * any installed mixer supports it.
- * @param info a Line.Info object describing the line for which support is queried
- * @return true if at least one matching line is
- * supported, otherwise false
+ * Indicates whether the system supports any lines that match the specified
+ * {@code Line.Info} object. A line is supported if any installed mixer
+ * supports it.
*
+ * @param info a {@code Line.Info} object describing the line for which
+ * support is queried
+ * @return {@code true} if at least one matching line is supported,
+ * otherwise {@code false}
* @see Mixer#isLineSupported(Line.Info)
*/
public static boolean isLineSupported(Line.Info info) {
@@ -371,40 +349,36 @@
/**
* Obtains a line that matches the description in the specified
- * Line.Info object.
- *
- *
If a DataLine is requested, and info
- * is an instance of DataLine.Info specifying at least
- * one fully qualified audio format, the last one
- * will be used as the default format of the returned
- * DataLine.
- *
- *
If system properties
- * javax.sound.sampled.Clip,
- * javax.sound.sampled.Port,
- * javax.sound.sampled.SourceDataLine and
- * javax.sound.sampled.TargetDataLine are defined
- * or they are defined in the file "sound.properties",
- * they are used to retrieve default lines.
- * For details, refer to the {@link AudioSystem class description}.
+ * {@code Line.Info} object.
+ *
+ * If a {@code DataLine} is requested, and {@code info} is an instance of + * {@code DataLine.Info} specifying at least one fully qualified audio + * format, the last one will be used as the default format of the returned + * {@code DataLine}. + *
+ * If system properties
+ * {@code javax.sound.sampled.Clip},
+ * {@code javax.sound.sampled.Port},
+ * {@code javax.sound.sampled.SourceDataLine} and
+ * {@code javax.sound.sampled.TargetDataLine} are defined or they are
+ * defined in the file "sound.properties", they are used to retrieve default
+ * lines. For details, refer to the {@link AudioSystem class description}.
*
- * If the respective property is not set, or the mixer
- * requested in the property is not installed or does not provide the
- * requested line, all installed mixers are queried for the
- * requested line type. A Line will be returned from the first mixer
- * providing the requested line type.
- *
- * @param info a Line.Info object describing the desired kind of line
- * @return a line of the requested kind
+ * If the respective property is not set, or the mixer requested in the
+ * property is not installed or does not provide the requested line, all
+ * installed mixers are queried for the requested line type. A Line will be
+ * returned from the first mixer providing the requested line type.
*
- * @throws LineUnavailableException if a matching line
- * is not available due to resource restrictions
- * @throws SecurityException if a matching line
- * is not available due to security restrictions
- * @throws IllegalArgumentException if the system does not
- * support at least one line matching the specified
- * Line.Info object
- * through any installed mixer
+ * @param info a {@code Line.Info} object describing the desired kind of
+ * line
+ * @return a line of the requested kind
+ * @throws LineUnavailableException if a matching line is not available due
+ * to resource restrictions
+ * @throws SecurityException if a matching line is not available due to
+ * security restrictions
+ * @throws IllegalArgumentException if the system does not support at least
+ * one line matching the specified {@code Line.Info} object through
+ * any installed mixer
*/
public static Line getLine(Line.Info info) throws LineUnavailableException {
LineUnavailableException lue = null;
@@ -479,37 +453,30 @@
info.toString() + " is supported.");
}
-
/**
- * Obtains a clip that can be used for playing back
- * an audio file or an audio stream. The returned clip
- * will be provided by the default system mixer, or,
- * if not possible, by any other mixer installed in the
- * system that supports a Clip
- * object.
- *
- *
The returned clip must be opened with the
- * open(AudioFormat) or
- * open(AudioInputStream) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- *
If the system property
- * javax.sound.sampled.Clip
- * is defined or it is defined in the file "sound.properties",
- * it is used to retrieve the default clip.
- * For details, refer to the {@link AudioSystem class description}.
+ * Obtains a clip that can be used for playing back an audio file or an
+ * audio stream. The returned clip will be provided by the default system
+ * mixer, or, if not possible, by any other mixer installed in the system
+ * that supports a {@code Clip} object.
+ *
+ * The returned clip must be opened with the {@code open(AudioFormat)} or + * {@code open(AudioInputStream)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. + *
+ * If the system property {@code javax.sound.sampled.Clip} is defined or it + * is defined in the file "sound.properties", it is used to retrieve the + * default clip. For details, refer to the + * {@link AudioSystem class description}. * * @return the desired clip object - * - * @throws LineUnavailableException if a clip object - * is not available due to resource restrictions - * @throws SecurityException if a clip object - * is not available due to security restrictions - * @throws IllegalArgumentException if the system does not - * support at least one clip instance through any installed mixer - * + * @throws LineUnavailableException if a clip object is not available due to + * resource restrictions + * @throws SecurityException if a clip object is not available due to + * security restrictions + * @throws IllegalArgumentException if the system does not support at least + * one clip instance through any installed mixer * @see #getClip(Mixer.Info) * @since 1.5 */ @@ -522,29 +489,26 @@ return (Clip) AudioSystem.getLine(info); } - /** - * Obtains a clip from the specified mixer that can be - * used for playing back an audio file or an audio stream. + * Obtains a clip from the specified mixer that can be used for playing back + * an audio file or an audio stream. + *
+ * The returned clip must be opened with the {@code open(AudioFormat)} or + * {@code open(AudioInputStream)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. * - *
The returned clip must be opened with the
- * open(AudioFormat) or
- * open(AudioInputStream) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- * @param mixerInfo a Mixer.Info object representing the
- * desired mixer, or null for the system default mixer
+ * @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 one clip through 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
+ * one clip through the specified mixer
* @see #getClip()
* @since 1.5
*/
@@ -558,45 +522,38 @@
return (Clip) mixer.getLine(info);
}
-
/**
- * Obtains a source data line that can be used for playing back
- * audio data in the format specified by the
- * AudioFormat object. The returned line
- * will be provided by the default system mixer, or,
- * if not possible, by any other mixer installed in the
- * system that supports a matching
- * SourceDataLine object.
- *
- *
The returned line should be opened with the
- * open(AudioFormat) or
- * open(AudioFormat, int) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- *
The returned SourceDataLine's default
- * audio format will be initialized with format.
+ * Obtains a source data line that can be used for playing back audio data
+ * in the format specified by the {@code AudioFormat} object. The returned
+ * line will be provided by the default system mixer, or, if not possible,
+ * by any other mixer installed in the system that supports a matching
+ * {@code SourceDataLine} object.
+ *
+ * The returned line should be opened with the {@code open(AudioFormat)} or + * {@code open(AudioFormat, int)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. + *
+ * The returned {@code SourceDataLine}'s default audio format will be + * initialized with {@code format}. + *
+ * If the system property {@code javax.sound.sampled.SourceDataLine} is + * defined or it is defined in the file "sound.properties", it is used to + * retrieve the default source data line. For details, refer to the + * {@link AudioSystem class description}. * - *
If the system property
- * javax.sound.sampled.SourceDataLine
- * is defined or it is defined in the file "sound.properties",
- * it is used to retrieve the default source data line.
- * For details, refer to the {@link AudioSystem class description}.
- *
- * @param format an AudioFormat object specifying
- * the supported audio format of the returned line,
- * or null for any audio format
- * @return the desired SourceDataLine object
- *
- * @throws LineUnavailableException if a matching source data line
- * is not available due to resource restrictions
- * @throws SecurityException if a matching source data line
- * is not available due to security restrictions
- * @throws IllegalArgumentException if the system does not
- * support at least one source data line supporting the
- * specified audio format through any installed mixer
- *
+ * @param format an {@code AudioFormat} object specifying the supported
+ * audio format of the returned line, or {@code null} for any audio
+ * format
+ * @return the desired {@code SourceDataLine} object
+ * @throws LineUnavailableException if a matching source data line is not
+ * available due to resource restrictions
+ * @throws SecurityException if a matching source data line is not available
+ * due to security restrictions
+ * @throws IllegalArgumentException if the system does not support at least
+ * one source data line supporting the specified audio format
+ * through any installed mixer
* @see #getSourceDataLine(AudioFormat, Mixer.Info)
* @since 1.5
*/
@@ -606,41 +563,33 @@
return (SourceDataLine) AudioSystem.getLine(info);
}
-
/**
- * Obtains a source data line that can be used for playing back
- * audio data in the format specified by the
- * AudioFormat object, provided by the mixer
- * specified by the Mixer.Info object.
- *
- *
The returned line should be opened with the
- * open(AudioFormat) or
- * open(AudioFormat, int) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- *
The returned SourceDataLine's default
- * audio format will be initialized with format.
+ * Obtains a source data line that can be used for playing back audio data
+ * in the format specified by the {@code AudioFormat} object, provided by
+ * the mixer specified by the {@code Mixer.Info} object.
+ *
+ * The returned line should be opened with the {@code open(AudioFormat)} or + * {@code open(AudioFormat, int)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. + *
+ * The returned {@code SourceDataLine}'s default audio format will be
+ * initialized with {@code format}.
*
- * @param format an AudioFormat object specifying
- * the supported audio format of the returned line,
- * or null for any audio format
- * @param mixerinfo a Mixer.Info object representing
- * the desired mixer, or null for the system
- * default mixer
- * @return the desired SourceDataLine object
- *
- * @throws LineUnavailableException if a matching source data
- * line is not available from the specified mixer due
- * to resource restrictions
- * @throws SecurityException if a matching source data line
- * is not available from the specified mixer due to
- * security restrictions
- * @throws IllegalArgumentException if the specified mixer does
- * not support at least one source data line supporting
- * the specified audio format
- *
+ * @param format an {@code AudioFormat} object specifying the supported
+ * audio format of the returned line, or {@code null} for any audio
+ * format
+ * @param mixerinfo a {@code Mixer.Info} object representing the desired
+ * mixer, or {@code null} for the system default mixer
+ * @return the desired {@code SourceDataLine} object
+ * @throws LineUnavailableException if a matching source data line is not
+ * available from the specified mixer due to resource restrictions
+ * @throws SecurityException if a matching source data line is not available
+ * from the specified mixer due to security restrictions
+ * @throws IllegalArgumentException if the specified mixer does not support
+ * at least one source data line supporting the specified audio
+ * format
* @see #getSourceDataLine(AudioFormat)
* @since 1.5
*/
@@ -650,47 +599,40 @@
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
Mixer mixer = AudioSystem.getMixer(mixerinfo);
return (SourceDataLine) mixer.getLine(info);
- }
-
+ }
/**
- * Obtains a target data line that can be used for recording
- * audio data in the format specified by the
- * AudioFormat object. The returned line
- * will be provided by the default system mixer, or,
- * if not possible, by any other mixer installed in the
- * system that supports a matching
- * TargetDataLine object.
- *
- *
The returned line should be opened with the
- * open(AudioFormat) or
- * open(AudioFormat, int) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- *
The returned TargetDataLine's default
- * audio format will be initialized with format.
+ * Obtains a target data line that can be used for recording audio data in
+ * the format specified by the {@code AudioFormat} object. The returned line
+ * will be provided by the default system mixer, or, if not possible, by any
+ * other mixer installed in the system that supports a matching
+ * {@code TargetDataLine} object.
+ *
+ * The returned line should be opened with the {@code open(AudioFormat)} or + * {@code open(AudioFormat, int)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. + *
+ * The returned {@code TargetDataLine}'s default audio format will be + * initialized with {@code format}. + *
+ * If the system property {@code javax.sound.sampled.TargetDataLine} is + * defined or it is defined in the file "sound.properties", it is used to + * retrieve the default target data line. For details, refer to the + * {@link AudioSystem class description}. * - *
If the system property
- * {@code javax.sound.sampled.TargetDataLine}
- * is defined or it is defined in the file "sound.properties",
- * it is used to retrieve the default target data line.
- * For details, refer to the {@link AudioSystem class description}.
- *
- * @param format an AudioFormat object specifying
- * the supported audio format of the returned line,
- * or null for any audio format
- * @return the desired TargetDataLine object
- *
- * @throws LineUnavailableException if a matching target data line
- * is not available due to resource restrictions
- * @throws SecurityException if a matching target data line
- * is not available due to security restrictions
- * @throws IllegalArgumentException if the system does not
- * support at least one target data line supporting the
- * specified audio format through any installed mixer
- *
+ * @param format an {@code AudioFormat} object specifying the supported
+ * audio format of the returned line, or {@code null} for any audio
+ * format
+ * @return the desired {@code TargetDataLine} object
+ * @throws LineUnavailableException if a matching target data line is not
+ * available due to resource restrictions
+ * @throws SecurityException if a matching target data line is not available
+ * due to security restrictions
+ * @throws IllegalArgumentException if the system does not support at least
+ * one target data line supporting the specified audio format
+ * through any installed mixer
* @see #getTargetDataLine(AudioFormat, Mixer.Info)
* @see AudioPermission
* @since 1.5
@@ -702,41 +644,33 @@
return (TargetDataLine) AudioSystem.getLine(info);
}
-
-
/**
- * Obtains a target data line that can be used for recording
- * audio data in the format specified by the
- * AudioFormat object, provided by the mixer
- * specified by the Mixer.Info object.
- *
- *
The returned line should be opened with the
- * open(AudioFormat) or
- * open(AudioFormat, int) method.
- *
- *
This is a high-level method that uses getMixer
- * and getLine internally.
- *
- *
The returned TargetDataLine's default
- * audio format will be initialized with format.
+ * Obtains a target data line that can be used for recording audio data in
+ * the format specified by the {@code AudioFormat} object, provided by the
+ * mixer specified by the {@code Mixer.Info} object.
+ *
+ * The returned line should be opened with the {@code open(AudioFormat)} or + * {@code open(AudioFormat, int)} method. + *
+ * This is a high-level method that uses {@code getMixer} and + * {@code getLine} internally. + *
+ * The returned {@code TargetDataLine}'s default audio format will be
+ * initialized with {@code format}.
*
- * @param format an AudioFormat object specifying
- * the supported audio format of the returned line,
- * or null for any audio format
- * @param mixerinfo a Mixer.Info object representing the
- * desired mixer, or null for the system default mixer
- * @return the desired TargetDataLine object
- *
- * @throws LineUnavailableException if a matching target data
- * line is not available from the specified mixer due
- * to resource restrictions
- * @throws SecurityException if a matching target data line
- * is not available from the specified mixer due to
- * security restrictions
- * @throws IllegalArgumentException if the specified mixer does
- * not support at least one target data line supporting
- * the specified audio format
- *
+ * @param format an {@code AudioFormat} object specifying the supported
+ * audio format of the returned line, or {@code null} for any audio
+ * format
+ * @param mixerinfo a {@code Mixer.Info} object representing the desired
+ * mixer, or {@code null} for the system default mixer
+ * @return the desired {@code TargetDataLine} object
+ * @throws LineUnavailableException if a matching target data line is not
+ * available from the specified mixer due to resource restrictions
+ * @throws SecurityException if a matching target data line is not available
+ * from the specified mixer due to security restrictions
+ * @throws IllegalArgumentException if the specified mixer does not support
+ * at least one target data line supporting the specified audio
+ * format
* @see #getTargetDataLine(AudioFormat)
* @see AudioPermission
* @since 1.5
@@ -750,17 +684,19 @@
return (TargetDataLine) mixer.getLine(info);
}
+ // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
- // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
/**
- * Obtains the encodings that the system can obtain from an
- * audio input 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 sourceEncodingis not supported,
- * an array of length 0 is returned. Otherwise, the array will have a length
- * of at least 1, representing sourceEncoding (no conversion).
+ * Obtains the encodings that the system can obtain from an audio input
+ * 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).
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
@@ -783,18 +719,18 @@
return encs2;
}
-
+ // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
- // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
/**
- * Obtains the encodings that the system can obtain from an
- * audio input stream with the specified format using the set
- * of installed format converters.
- * @param sourceFormat the audio format for which conversion
- * is queried
- * @return array of encodings. If sourceFormatis not supported,
- * an array of length 0 is returned. Otherwise, the array will have a length
- * of at least 1, representing the encoding of sourceFormat (no conversion).
+ * Obtains the encodings that the system can obtain from an audio input
+ * stream with the specified format using the set of installed format
+ * converters.
+ *
+ * @param sourceFormat the audio format for which conversion is queried
+ * @return array of encodings. If {@code sourceFormat}is not supported, an
+ * array of length 0 is returned. Otherwise, the array will have a
+ * length of at least 1, representing the encoding of
+ * {@code sourceFormat} (no conversion).
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat) {
@@ -826,15 +762,14 @@
return encs2;
}
-
/**
- * Indicates whether an audio input stream of the specified encoding
- * can be obtained from an audio input stream that has the specified
- * format.
- * @param targetEncoding the desired encoding after conversion
- * @param sourceFormat the audio format before conversion
- * @return true if the conversion is supported,
- * otherwise false
+ * Indicates whether an audio input stream of the specified encoding can be
+ * obtained from an audio input stream that has the specified format.
+ *
+ * @param targetEncoding the desired encoding after conversion
+ * @param sourceFormat the audio format before conversion
+ * @return {@code true} if the conversion is supported, otherwise
+ * {@code false}
*/
public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
@@ -850,12 +785,12 @@
return false;
}
-
/**
- * Obtains an audio input stream of the indicated encoding, by converting the
- * provided audio input stream.
- * @param targetEncoding the desired encoding after conversion
- * @param sourceStream the stream to be converted
+ * Obtains an audio input stream of the indicated encoding, by converting
+ * the provided audio input stream.
+ *
+ * @param targetEncoding the desired encoding after conversion
+ * @param sourceStream the stream to be converted
* @return an audio input stream of the indicated encoding
* @throws IllegalArgumentException if the conversion is not supported
* @see #getTargetEncodings(AudioFormat.Encoding)
@@ -878,15 +813,15 @@
throw new IllegalArgumentException("Unsupported conversion: " + targetEncoding + " from " + sourceStream.getFormat());
}
-
/**
- * Obtains the formats that have a particular encoding and that the system can
- * obtain from a stream of the specified format using the set of
+ * Obtains the formats that have a particular encoding and that the system
+ * can obtain from a stream of the specified format using the set of
* installed format converters.
- * @param targetEncoding the desired encoding after conversion
- * @param sourceFormat the audio format before conversion
- * @return array of formats. If no formats of the specified
- * encoding are supported, an array of length 0 is returned.
+ *
+ * @param targetEncoding the desired encoding after conversion
+ * @param sourceFormat the audio format before conversion
+ * @return array of formats. If no formats of the specified encoding are
+ * supported, an array of length 0 is returned.
*/
public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
@@ -918,16 +853,15 @@
return fmts2;
}
-
/**
- * Indicates whether an audio input stream of a specified format
- * can be obtained from an audio input stream of another specified format.
- * @param targetFormat the desired audio format after conversion
- * @param sourceFormat the audio format before conversion
- * @return true if the conversion is supported,
- * otherwise false
+ * Indicates whether an audio input stream of a specified format can be
+ * obtained from an audio input stream of another specified format.
+ *
+ * @param targetFormat the desired audio format after conversion
+ * @param sourceFormat the audio format before conversion
+ * @return {@code true} if the conversion is supported, otherwise
+ * {@code false}
*/
-
public static boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) {
List codecs = getFormatConversionProviders();
@@ -941,15 +875,15 @@
return false;
}
-
/**
* Obtains an audio input stream of the indicated format, by converting the
* provided audio input stream.
- * @param targetFormat the desired audio format after conversion
- * @param sourceStream the stream to be converted
+ *
+ * @param targetFormat the desired audio format after conversion
+ * @param sourceStream the stream to be converted
* @return an audio input stream of the indicated format
* @throws IllegalArgumentException if the conversion is not supported
- * #see #getTargetEncodings(AudioFormat)
+ * @see #getTargetEncodings(AudioFormat)
* @see #getTargetFormats(AudioFormat.Encoding, AudioFormat)
* @see #isConversionSupported(AudioFormat, AudioFormat)
* @see #getAudioInputStream(AudioFormat.Encoding, AudioInputStream)
@@ -974,20 +908,22 @@
throw new IllegalArgumentException("Unsupported conversion: " + targetFormat + " from " + sourceStream.getFormat());
}
-
/**
- * Obtains the audio file format of the provided input stream. The stream must
- * point to valid audio file data. The implementation of this method may require
- * multiple parsers to examine the stream to determine whether they support it.
- * These parsers must be able to mark the stream, read enough data to determine whether they
- * support the stream, and, if not, reset the stream's read pointer to its original
- * position. If the input stream does not support these operations, this method may fail
- * with an IOException.
- * @param stream the input stream from which file format information should be
- * extracted
- * @return an AudioFileFormat object describing the stream's audio file format
- * @throws UnsupportedAudioFileException if the stream does not point to valid audio
- * file data recognized by the system
+ * Obtains the audio file format of the provided input stream. The stream
+ * must point to valid audio file data. The implementation of this method
+ * may require multiple parsers to examine the stream to determine whether
+ * they support it. These parsers must be able to mark the stream, read
+ * enough data to determine whether they support the stream, and, if not,
+ * reset the stream's read pointer to its original position. If the input
+ * stream does not support these operations, this method may fail with an
+ * {@code IOException}.
+ *
+ * @param stream the input stream from which file format information should
+ * be extracted
+ * @return an {@code AudioFileFormat} object describing the stream's audio
+ * file format
+ * @throws UnsupportedAudioFileException if the stream does not point to
+ * valid audio file data recognized by the system
* @throws IOException if an input/output exception occurs
* @see InputStream#markSupported
* @see InputStream#mark
@@ -1016,13 +952,15 @@
}
/**
- * 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 AudioFileFormat object describing the audio file format
- * @throws UnsupportedAudioFileException if the URL does not point to valid audio
- * file data recognized by the system
+ * 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
*/
public static AudioFileFormat getAudioFileFormat(URL url)
@@ -1049,13 +987,15 @@
}
/**
- * Obtains the audio file format of the specified File. The File must
- * point to valid audio file data.
- * @param file the File from which file format information should be
- * extracted
- * @return an AudioFileFormat object describing the audio file format
- * @throws UnsupportedAudioFileException if the File does not point to valid audio
- * file data recognized by the system
+ * Obtains the audio file format of the specified {@code File}. The
+ * {@code File} must point to valid audio file data.
+ *
+ * @param file the {@code File} from which file format information should
+ * be extracted
+ * @return an {@code AudioFileFormat} object describing the audio file
+ * format
+ * @throws UnsupportedAudioFileException if the {@code File} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
*/
public static AudioFileFormat getAudioFileFormat(File file)
@@ -1081,22 +1021,22 @@
}
}
-
/**
- * Obtains an audio input stream from the provided input stream. The stream must
- * point to valid audio file data. The implementation of this method may
- * require multiple parsers to
- * examine the stream to determine whether they support it. These parsers must
- * be able to mark the stream, read enough data to determine whether they
- * support the stream, and, if not, reset the stream's read pointer to its original
- * position. If the input stream does not support these operation, this method may fail
- * with an IOException.
- * @param stream the input stream from which the AudioInputStream should be
- * constructed
- * @return an AudioInputStream object based on the audio file data contained
- * in the input stream.
- * @throws UnsupportedAudioFileException if the stream does not point to valid audio
- * file data recognized by the system
+ * Obtains an audio input stream from the provided input stream. The stream
+ * must point to valid audio file data. The implementation of this method
+ * may require multiple parsers to examine the stream to determine whether
+ * they support it. These parsers must be able to mark the stream, read
+ * enough data to determine whether they support the stream, and, if not,
+ * reset the stream's read pointer to its original position. If the input
+ * stream does not support these operation, this method may fail with an
+ * {@code IOException}.
+ *
+ * @param stream the input stream from which the {@code AudioInputStream}
+ * should be constructed
+ * @return an {@code AudioInputStream} object based on the audio file data
+ * contained in the input stream
+ * @throws UnsupportedAudioFileException if the stream does not point to
+ * valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @see InputStream#markSupported
* @see InputStream#mark
@@ -1125,14 +1065,15 @@
}
/**
- * 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 AudioInputStream should be
- * constructed
- * @return an 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
+ * 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
*/
public static AudioInputStream getAudioInputStream(URL url)
@@ -1159,14 +1100,15 @@
}
/**
- * Obtains an audio input stream from the provided File. The File must
- * point to valid audio file data.
- * @param file the File for which the AudioInputStream should be
- * constructed
- * @return an AudioInputStream object based on the audio file data pointed
- * to by the File
- * @throws UnsupportedAudioFileException if the File does not point to valid audio
- * file data recognized by the system
+ * Obtains an audio input stream from the provided {@code File}. The
+ * {@code File} must point to valid audio file data.
+ *
+ * @param file the {@code File} for which the {@code AudioInputStream}
+ * should be constructed
+ * @return an {@code AudioInputStream} object based on the audio file data
+ * pointed to by the {@code File}
+ * @throws UnsupportedAudioFileException if the {@code File} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
*/
public static AudioInputStream getAudioInputStream(File file)
@@ -1192,11 +1134,12 @@
}
}
-
/**
- * Obtains the file types for which file writing support is provided by the system.
- * @return array of unique file types. If no file types are supported,
- * an array of length 0 is returned.
+ * Obtains the file types for which file writing support is provided by the
+ * system.
+ *
+ * @return array of unique file types. If no file types are supported, an
+ * array of length 0 is returned.
*/
public static AudioFileFormat.Type[] getAudioFileTypes() {
List providers = getAudioFileWriters();
@@ -1214,13 +1157,13 @@
return returnTypes;
}
-
/**
- * Indicates whether file writing support for the specified file type is provided
- * by the system.
- * @param fileType the file type for which write capabilities are queried
- * @return true if the file type is supported,
- * otherwise false
+ * Indicates whether file writing support for the specified file type is
+ * provided by the system.
+ *
+ * @param fileType the file type for which write capabilities are queried
+ * @return {@code true} if the file type is supported, otherwise
+ * {@code false}
*/
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType) {
@@ -1235,14 +1178,14 @@
return false;
}
-
/**
- * 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.
+ * 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.
*/
public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) {
List providers = getAudioFileWriters();
@@ -1260,14 +1203,14 @@
return returnTypes;
}
-
/**
* Indicates whether an audio file of the specified file type can be written
* from the indicated audio input stream.
- * @param fileType the file type for which write capabilities are queried
- * @param stream the stream for which file-writing support is queried
- * @return true if the file type is supported for this audio input stream,
- * otherwise false
+ *
+ * @param fileType the file type for which write capabilities are queried
+ * @param stream the stream for which file-writing support is queried
+ * @return {@code true} if the file type is supported for this audio input
+ * stream, otherwise {@code false}
*/
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
AudioInputStream stream) {
@@ -1283,25 +1226,24 @@
return false;
}
-
/**
- * 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 AudioSystem.NOT_SPECIFIED.
+ * 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
+ * @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
* @return the number of bytes written to the output stream
* @throws IOException if an input/output exception occurs
- * @throws IllegalArgumentException if the file type is not supported by
- * the system
+ * @throws IllegalArgumentException if the file type is not supported by the
+ * system
* @see #isFileTypeSupported
- * @see #getAudioFileTypes
+ * @see #getAudioFileTypes
*/
public static int write(AudioInputStream stream, AudioFileFormat.Type fileType,
OutputStream out) throws IOException {
@@ -1328,20 +1270,20 @@
}
}
-
/**
- * Writes a stream of bytes representing an audio file of the specified file type
- * to the external file provided.
- * @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 external file to which the file data should be written
+ * Writes a stream of bytes representing an audio file of the specified file
+ * type to the external file provided.
+ *
+ * @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 external file to which the file data should be written
* @return the number of bytes written to the file
* @throws IOException if an I/O exception occurs
- * @throws IllegalArgumentException if the file type is not supported by
- * the system
+ * @throws IllegalArgumentException if the file type is not supported by the
+ * system
* @see #isFileTypeSupported
- * @see #getAudioFileTypes
+ * @see #getAudioFileTypes
*/
public static int write(AudioInputStream stream, AudioFileFormat.Type fileType,
File out) throws IOException {
@@ -1368,7 +1310,6 @@
}
}
-
// METHODS FOR INTERNAL IMPLEMENTATION USE
/**
@@ -1378,55 +1319,54 @@
return getProviders(MixerProvider.class);
}
-
/**
- * Obtains the set of format converters (codecs, transcoders, etc.)
- * that are currently installed on the system.
- * @return an array of
- * {@link javax.sound.sampled.spi.FormatConversionProvider
- * FormatConversionProvider}
- * objects representing the available format converters. If no format
- * converters readers are available on the system, an array of length 0 is
- * returned.
+ * Obtains the set of format converters (codecs, transcoders, etc.) that are
+ * currently installed on the system.
+ *
+ * @return an array of {@link javax.sound.sampled.spi.FormatConversionProvider
+ * FormatConversionProvider} objects representing the available
+ * format converters. If no format converters readers are available
+ * on the system, an array of length 0 is returned.
*/
private static List getFormatConversionProviders() {
return getProviders(FormatConversionProvider.class);
}
-
/**
- * Obtains the set of audio file readers that are currently installed on the system.
- * @return a List of
- * {@link javax.sound.sampled.spi.AudioFileReader
- * AudioFileReader}
- * objects representing the installed audio file readers. If no audio file
- * readers are available on the system, an empty List is returned.
+ * Obtains the set of audio file readers that are currently installed on the
+ * system.
+ *
+ * @return a List of {@link javax.sound.sampled.spi.AudioFileReader
+ * AudioFileReader} objects representing the installed audio file
+ * readers. If no audio file readers are available on the system, an
+ * empty List is returned.
*/
private static List getAudioFileReaders() {
return getProviders(AudioFileReader.class);
}
-
/**
- * Obtains the set of audio file writers that are currently installed on the system.
- * @return a List of
- * {@link javax.sound.samples.spi.AudioFileWriter AudioFileWriter}
- * objects representing the available audio file writers. If no audio file
- * writers are available on the system, an empty List is returned.
+ * Obtains the set of audio file writers that are currently installed on the
+ * system.
+ *
+ * @return a List of {@link javax.sound.sampled.spi.AudioFileWriter
+ * AudioFileWriter} objects representing the available audio file
+ * writers. If no audio file writers are available on the system, an
+ * empty List is returned.
*/
private static List getAudioFileWriters() {
return getProviders(AudioFileWriter.class);
}
-
-
- /** Attempts to locate and return a default Mixer that provides lines
- * of the specified type.
+ /**
+ * Attempts to locate and return a default Mixer that provides lines of the
+ * specified type.
*
- * @param providers the installed mixer providers
- * @param info The requested line type
- * TargetDataLine.class, Clip.class or Port.class.
- * @return a Mixer that matches the requirements, or null if no default mixer found
+ * @param providers the installed mixer providers
+ * @param info The requested line type TargetDataLine.class, Clip.class or
+ * Port.class
+ * @return a Mixer that matches the requirements, or null if no default
+ * mixer found
*/
private static Mixer getDefaultMixer(List providers, Line.Info info) {
Class lineClass = info.getLineClass();
@@ -1469,16 +1409,13 @@
return null;
}
-
-
- /** Return a MixerProvider of a given class from the list of
- MixerProviders.
-
- This method never requires the returned Mixer to do mixing.
- @param providerClassName The class name of the provider to be returned.
- @param providers The list of MixerProviders that is searched.
- @return A MixerProvider of the requested class, or null if none is
- found.
+ /**
+ * Return a MixerProvider of a given class from the list of MixerProviders.
+ * This method never requires the returned Mixer to do mixing.
+ *
+ * @param providerClassName The class name of the provider to be returned
+ * @param providers The list of MixerProviders that is searched
+ * @return A MixerProvider of the requested class, or null if none is found
*/
private static MixerProvider getNamedProvider(String providerClassName,
List providers) {
@@ -1491,15 +1428,14 @@
return null;
}
-
- /** Return a Mixer with a given name from a given MixerProvider.
- This method never requires the returned Mixer to do mixing.
- @param mixerName The name of the Mixer to be returned.
- @param provider The MixerProvider to check for Mixers.
- @param info The type of line the returned Mixer is required to
- support.
-
- @return A Mixer matching the requirements, or null if none is found.
+ /**
+ * Return a Mixer with a given name from a given MixerProvider. This method
+ * never requires the returned Mixer to do mixing.
+ *
+ * @param mixerName The name of the Mixer to be returned
+ * @param provider The MixerProvider to check for Mixers
+ * @param info The type of line the returned Mixer is required to support
+ * @return A Mixer matching the requirements, or null if none is found
*/
private static Mixer getNamedMixer(String mixerName,
MixerProvider provider,
@@ -1516,14 +1452,14 @@
return null;
}
-
- /** From a List of MixerProviders, return a Mixer with a given name.
- This method never requires the returned Mixer to do mixing.
- @param mixerName The name of the Mixer to be returned.
- @param providers The List of MixerProviders to check for Mixers.
- @param info The type of line the returned Mixer is required to
- support.
- @return A Mixer matching the requirements, or null if none is found.
+ /**
+ * From a List of MixerProviders, return a Mixer with a given name. This
+ * method never requires the returned Mixer to do mixing.
+ *
+ * @param mixerName The name of the Mixer to be returned
+ * @param providers The List of MixerProviders to check for Mixers
+ * @param info The type of line the returned Mixer is required to support
+ * @return A Mixer matching the requirements, or null if none is found
*/
private static Mixer getNamedMixer(String mixerName,
List providers,
@@ -1538,16 +1474,14 @@
return null;
}
-
- /** From a given MixerProvider, return the first appropriate Mixer.
- @param provider The MixerProvider to check for Mixers.
- @param info The type of line the returned Mixer is required to
- support.
- @param isMixingRequired If true, only Mixers that support mixing are
- returned for line types of SourceDataLine and Clip.
-
- @return A Mixer that is considered appropriate, or null
- if none is found.
+ /**
+ * From a given MixerProvider, return the first appropriate Mixer.
+ *
+ * @param provider The MixerProvider to check for Mixers
+ * @param info The type of line the returned Mixer is required to support
+ * @param isMixingRequired If true, only Mixers that support mixing are
+ * returned for line types of SourceDataLine and Clip
+ * @return A Mixer that is considered appropriate, or null if none is found
*/
private static Mixer getFirstMixer(MixerProvider provider,
Line.Info info,
@@ -1562,15 +1496,14 @@
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 true if the mixer is considered appropriate according to the
- rules given above, false otherwise.
+ /**
+ * 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,
@@ -1588,19 +1521,16 @@
return true;
}
-
-
/**
- * Like getMixerInfo, but return List
+ * Like getMixerInfo, but return List.
*/
private static List getMixerInfoList() {
List providers = getMixerProviders();
return getMixerInfoList(providers);
}
-
/**
- * Like getMixerInfo, but return List
+ * Like getMixerInfo, but return List.
*/
private static List getMixerInfoList(List providers) {
List infos = new ArrayList();
@@ -1619,12 +1549,12 @@
return infos;
}
-
/**
- * Obtains the set of services currently installed on the system
- * using the SPI mechanism in 1.3.
- * @return a List of instances of providers for the requested service.
- * If no providers are available, a vector of length 0 will be returned.
+ * Obtains the set of services currently installed on the system using the
+ * SPI mechanism in 1.3.
+ *
+ * @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);
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/BooleanControl.java
--- a/jdk/src/share/classes/javax/sound/sampled/BooleanControl.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/BooleanControl.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,34 +26,29 @@
package javax.sound.sampled;
/**
- * A BooleanControl provides the ability to switch between
- * two possible settings that affect a line's audio. The settings are boolean
- * values (true and false). A graphical user interface
- * might represent the control by a two-state button, an on/off switch, two
- * mutually exclusive buttons, or a checkbox (among other possibilities).
- * For example, depressing a button might activate a
- * {@link BooleanControl.Type#MUTE MUTE} control to silence
- * the line's audio.
+ * A {@code BooleanControl} provides the ability to switch between two possible
+ * settings that affect a line's audio. The settings are boolean values
+ * ({@code true} and {@code false}). A graphical user interface might represent
+ * the control by a two-state button, an on/off switch, two mutually exclusive
+ * buttons, or a checkbox (among other possibilities). For example, depressing a
+ * button might activate a {@link BooleanControl.Type#MUTE MUTE} control to
+ * silence the line's audio.
*
- * As with other {@link Control} subclasses, a method is
- * provided that returns string labels for the values, suitable for
- * display in the user interface.
+ * As with other {@code Control} subclasses, a method is provided that returns
+ * string labels for the values, suitable for display in the user interface.
*
* @author Kara Kytle
* @since 1.3
*/
public abstract class BooleanControl extends Control {
-
- // INSTANCE VARIABLES
-
/**
- * The true state label, such as "true" or "on."
+ * The {@code true} state label, such as "true" or "on".
*/
private final String trueStateLabel;
/**
- * The false state label, such as "false" or "off."
+ * The {@code false} state label, such as "false" or "off".
*/
private final String falseStateLabel;
@@ -62,19 +57,15 @@
*/
private boolean value;
-
- // CONSTRUCTORS
-
-
/**
* Constructs a new boolean control object with the given parameters.
*
- * @param type the type of control represented this float control object
- * @param initialValue the initial control value
- * @param trueStateLabel the label for the state represented by true,
- * such as "true" or "on."
- * @param falseStateLabel the label for the state represented by false,
- * such as "false" or "off."
+ * @param type the type of control represented this float control object
+ * @param initialValue the initial control value
+ * @param trueStateLabel the label for the state represented by
+ * {@code true}, such as "true" or "on"
+ * @param falseStateLabel the label for the state represented by
+ * {@code false}, such as "false" or "off"
*/
protected BooleanControl(Type type, boolean initialValue, String trueStateLabel, String falseStateLabel) {
@@ -84,110 +75,88 @@
this.falseStateLabel = falseStateLabel;
}
-
/**
- * Constructs a new boolean control object with the given parameters.
- * The labels for the true and false states
- * default to "true" and "false."
+ * Constructs a new boolean control object with the given parameters. The
+ * labels for the {@code true} and {@code false} states default to "true"
+ * and "false".
*
- * @param type the type of control represented by this float control object
- * @param initialValue the initial control value
+ * @param type the type of control represented by this float control object
+ * @param initialValue the initial control value
*/
protected BooleanControl(Type type, boolean initialValue) {
this(type, initialValue, "true", "false");
}
-
- // METHODS
-
-
/**
- * Sets the current value for the control. The default
- * implementation simply sets the value as indicated.
- * Some controls require that their line be open before they can be affected
- * by setting a value.
- * @param value desired new value.
+ * Sets the current value for the control. The default implementation simply
+ * sets the value as indicated. Some controls require that their line be
+ * open before they can be affected by setting a value.
+ *
+ * @param value desired new value
*/
public void setValue(boolean value) {
this.value = value;
}
-
-
/**
* Obtains this control's current value.
- * @return current value.
+ *
+ * @return current value
*/
public boolean getValue() {
return value;
}
-
/**
* Obtains the label for the specified state.
- * @param state the state whose label will be returned
- * @return the label for the specified state, such as "true" or "on"
- * for true, or "false" or "off" for false.
+ *
+ * @param state the state whose label will be returned
+ * @return the label for the specified state, such as "true" or "on" for
+ * {@code true}, or "false" or "off" for {@code false}
*/
public String getStateLabel(boolean state) {
return ((state == true) ? trueStateLabel : falseStateLabel);
}
-
-
- // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
-
-
/**
- * Provides a string representation of the control
+ * Provides a string representation of the control.
+ *
* @return a string description
*/
+ @Override
public String toString() {
return new String(super.toString() + " with current value: " + getStateLabel(getValue()));
}
-
- // INNER CLASSES
-
-
/**
- * An instance of the BooleanControl.Type class identifies one kind of
- * boolean control. Static instances are provided for the
- * common types.
+ * An instance of the {@code BooleanControl.Type} class identifies one kind
+ * of boolean control. Static instances are provided for the common types.
*
* @author Kara Kytle
* @since 1.3
*/
public static class Type extends Control.Type {
-
- // TYPE DEFINES
-
-
/**
- * Represents a control for the mute status of a line.
- * Note that mute status does not affect gain.
+ * Represents a control for the mute status of a line. Note that mute
+ * status does not affect gain.
*/
public static final Type MUTE = new Type("Mute");
/**
- * Represents a control for whether reverberation is applied
- * to a line. Note that the status of this control not affect
- * the reverberation settings for a line, but does affect whether
- * these settings are used.
+ * Represents a control for whether reverberation is applied to a line.
+ * Note that the status of this control not affect the reverberation
+ * settings for a line, but does affect whether these settings are used.
*/
public static final Type APPLY_REVERB = new Type("Apply Reverb");
-
- // CONSTRUCTOR
-
-
/**
* Constructs a new boolean control type.
- * @param name the name of the new boolean control type
+ *
+ * @param name the name of the new boolean control type
*/
- protected Type(String name) {
+ protected Type(final String name) {
super(name);
}
- } // class Type
+ }
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/Clip.java
--- a/jdk/src/share/classes/javax/sound/sampled/Clip.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/Clip.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,188 +25,184 @@
package javax.sound.sampled;
-import java.io.InputStream;
import java.io.IOException;
/**
- * The Clip interface represents a special kind of data line whose
- * audio data can be loaded prior to playback, instead of being streamed in
- * real time.
+ * The {@code Clip} interface represents a special kind of data line whose audio
+ * data can be loaded prior to playback, instead of being streamed in real time.
*
- * Because the data is pre-loaded and has a known length, you can set a clip - * to start playing at any position in its audio data. You can also create a - * loop, so that when the clip is played it will cycle repeatedly. Loops are - * specified with a starting and ending sample frame, along with the number of - * times that the loop should be played. + * Because the data is pre-loaded and has a known length, you can set a clip to + * start playing at any position in its audio data. You can also create a loop, + * so that when the clip is played it will cycle repeatedly. Loops are specified + * with a starting and ending sample frame, along with the number of times that + * the loop should be played. *
- * Clips may be obtained from a {@link Mixer} that supports lines
- * of this type. Data is loaded into a clip when it is opened.
+ * Clips may be obtained from a {@link Mixer} that supports lines of this type.
+ * Data is loaded into a clip when it is opened.
*
- * Playback of an audio clip may be started and stopped using the start
- * and stop methods. These methods do not reset the media position;
- * start causes playback to continue from the position where playback
- * was last stopped. To restart playback from the beginning of the clip's audio
- * data, simply follow the invocation of {@link DataLine#stop stop}
- * with setFramePosition(0), which rewinds the media to the beginning
- * of the clip.
+ * Playback of an audio clip may be started and stopped using the
+ * {@link #start start} and {@link #stop stop} methods. These methods do not
+ * reset the media position; {@code start} causes playback to continue from the
+ * position where playback was last stopped. To restart playback from the
+ * beginning of the clip's audio data, simply follow the invocation of
+ * {@code stop} with {@code setFramePosition(0)}, which rewinds the media to the
+ * beginning of the clip.
*
* @author Kara Kytle
* @since 1.3
*/
public interface Clip extends DataLine {
-
/**
* A value indicating that looping should continue indefinitely rather than
* complete after a specific number of loops.
+ *
* @see #loop
*/
- public static final int LOOP_CONTINUOUSLY = -1;
+ int LOOP_CONTINUOUSLY = -1;
/**
- * Opens the clip, meaning that it should acquire any required
- * system resources and become operational. The clip is opened
- * with the format and audio data indicated.
- * If this operation succeeds, the line is marked as open and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched
- * to the line's listeners.
+ * Opens the clip, meaning that it should acquire any required system
+ * resources and become operational. The clip is opened with the format and
+ * audio data indicated. If this operation succeeds, the line is marked as
+ * open and an {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
+ * line's listeners.
*
- * Invoking this method on a line which is already open is illegal - * and may result in an IllegalStateException. + * Invoking this method on a line which is already open is illegal and may + * result in an {@code IllegalStateException}. *
- * Note that some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * {@link LineUnavailableException}.
+ * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+ * such a line will always result in a {@code LineUnavailableException}.
*
- * @param format the format of the supplied audio data
- * @param data a byte array containing audio data to load into the clip
- * @param offset the point at which to start copying, expressed in
- * bytes from the beginning of the array
- * @param bufferSize the number of bytes
- * of data to load into the clip from the array.
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IllegalArgumentException if the buffer size does not represent
- * an integral number of sample frames,
- * or if format is not fully specified or invalid
+ * @param format the format of the supplied audio data
+ * @param data a byte array containing audio data to load into the clip
+ * @param offset the point at which to start copying, expressed in
+ * bytes from the beginning of the array
+ * @param bufferSize the number of bytes of data to load into the
+ * clip from the array
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IllegalArgumentException if the buffer size does not represent an
+ * integral number of sample frames, or if {@code format} is not
+ * fully specified or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #close
* @see #isOpen
* @see LineListener
*/
- public void open(AudioFormat format, byte[] data, int offset, int bufferSize) throws LineUnavailableException;
+ void open(AudioFormat format, byte[] data, int offset, int bufferSize)
+ throws LineUnavailableException;
/**
- * Opens the clip with the format and audio data present in the provided audio
- * input stream. Opening a clip means that it should acquire any required
- * system resources and become operational. If this operation
- * input stream. If this operation
- * succeeds, the line is marked open and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched
- * to the line's listeners.
+ * Opens the clip with the format and audio data present in the provided
+ * audio input stream. Opening a clip means that it should acquire any
+ * required system resources and become operational. If this operation input
+ * stream. If this operation succeeds, the line is marked open and an
+ * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+ * listeners.
*
- * Invoking this method on a line which is already open is illegal - * and may result in an IllegalStateException. + * Invoking this method on a line which is already open is illegal and may + * result in an {@code IllegalStateException}. *
- * Note that some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * {@link LineUnavailableException}.
+ * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+ * such a line will always result in a {@code LineUnavailableException}.
*
- * @param stream an audio input stream from which audio data will be read into
- * the clip
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IOException if an I/O exception occurs during reading of
- * the stream
- * @throws IllegalArgumentException if the stream's audio format
- * is not fully specified or invalid
+ * @param stream an audio input stream from which audio data will be read
+ * into the clip
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IOException if an I/O exception occurs during reading of the
+ * stream
+ * @throws IllegalArgumentException if the stream's audio format is not
+ * fully specified or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #close
* @see #isOpen
* @see LineListener
*/
- public void open(AudioInputStream stream) throws LineUnavailableException, IOException;
+ void open(AudioInputStream stream)
+ throws LineUnavailableException, IOException;
/**
* Obtains the media length in sample frames.
- * @return the media length, expressed in sample frames,
- * or AudioSystem.NOT_SPECIFIED if the line is not open.
+ *
+ * @return the media length, expressed in sample frames, or
+ * {@code AudioSystem.NOT_SPECIFIED} if the line is not open
* @see AudioSystem#NOT_SPECIFIED
*/
- public int getFrameLength();
+ int getFrameLength();
/**
- * Obtains the media duration in microseconds
- * @return the media duration, expressed in microseconds,
- * or AudioSystem.NOT_SPECIFIED if the line is not open.
+ * Obtains the media duration in microseconds.
+ *
+ * @return the media duration, expressed in microseconds, or
+ * {@code AudioSystem.NOT_SPECIFIED} if the line is not open
* @see AudioSystem#NOT_SPECIFIED
*/
- public long getMicrosecondLength();
+ long getMicrosecondLength();
/**
- * Sets the media position in sample frames. The position is zero-based;
- * the first frame is frame number zero. When the clip begins playing the
- * next time, it will start by playing the frame at this position.
+ * Sets the media position in sample frames. The position is zero-based; the
+ * first frame is frame number zero. When the clip begins playing the next
+ * time, it will start by playing the frame at this position.
*
* To obtain the current position in sample frames, use the
- * {@link DataLine#getFramePosition getFramePosition}
- * method of DataLine.
+ * {@link DataLine#getFramePosition getFramePosition} method of
+ * {@code DataLine}.
*
- * @param frames the desired new media position, expressed in sample frames
+ * @param frames the desired new media position, expressed in sample frames
*/
- public void setFramePosition(int frames);
+ void setFramePosition(int frames);
/**
- * Sets the media position in microseconds. When the clip begins playing the
- * next time, it will start at this position.
- * The level of precision is not guaranteed. For example, an implementation
- * might calculate the microsecond position from the current frame position
- * and the audio sample frame rate. The precision in microseconds would
- * then be limited to the number of microseconds per sample frame.
+ * Sets the media position in microseconds. When the clip begins playing the
+ * next time, it will start at this position. The level of precision is not
+ * guaranteed. For example, an implementation might calculate the
+ * microsecond position from the current frame position and the audio sample
+ * frame rate. The precision in microseconds would then be limited to the
+ * number of microseconds per sample frame.
*
* To obtain the current position in microseconds, use the
- * {@link DataLine#getMicrosecondPosition getMicrosecondPosition}
- * method of DataLine.
+ * {@link DataLine#getMicrosecondPosition getMicrosecondPosition} method of
+ * {@code DataLine}.
*
- * @param microseconds the desired new media position, expressed in microseconds
+ * @param microseconds the desired new media position, expressed in
+ * microseconds
*/
- public void setMicrosecondPosition(long microseconds);
+ void setMicrosecondPosition(long microseconds);
/**
- * Sets the first and last sample frames that will be played in
- * the loop. The ending point must be greater than
- * or equal to the starting point, and both must fall within the
- * the size of the loaded media. A value of 0 for the starting
- * point means the beginning of the loaded media. Similarly, a value of -1
- * for the ending point indicates the last frame of the media.
- * @param start the loop's starting position, in sample frames (zero-based)
- * @param end the loop's ending position, in sample frames (zero-based), or
- * -1 to indicate the final frame
- * @throws IllegalArgumentException if the requested
- * loop points cannot be set, usually because one or both falls outside
- * the media's duration or because the ending point is
- * before the starting point
+ * Sets the first and last sample frames that will be played in the loop.
+ * The ending point must be greater than or equal to the starting point, and
+ * both must fall within the the size of the loaded media. A value of 0 for
+ * the starting point means the beginning of the loaded media. Similarly, a
+ * value of -1 for the ending point indicates the last frame of the media.
+ *
+ * @param start the loop's starting position, in sample frames (zero-based)
+ * @param end the loop's ending position, in sample frames (zero-based),
+ * or -1 to indicate the final frame
+ * @throws IllegalArgumentException if the requested loop points cannot be
+ * set, usually because one or both falls outside the media's
+ * duration or because the ending point is before the starting point
*/
- public void setLoopPoints(int start, int end);
+ void setLoopPoints(int start, int end);
/**
- * Starts looping playback from the current position. Playback will
- * continue to the loop's end point, then loop back to the loop start point
- * count times, and finally continue playback to the end of
- * the clip.
+ * Starts looping playback from the current position. Playback will continue
+ * to the loop's end point, then loop back to the loop start point
+ * {@code count} times, and finally continue playback to the end of the
+ * clip.
*
* If the current position when this method is invoked is greater than the - * loop end point, playback simply continues to the - * end of the clip without looping. + * loop end point, playback simply continues to the end of the clip without + * looping. *
- * A count value of 0 indicates that any current looping should
- * cease and playback should continue to the end of the clip. The behavior
+ * A {@code count} value of 0 indicates that any current looping should
+ * cease and playback should continue to the end of the clip. The behavior
* is undefined when this method is invoked with any other value during a
* loop operation.
*
@@ -214,10 +210,10 @@
* cleared; the behavior of subsequent loop and start requests is not
* affected by an interrupted loop operation.
*
- * @param count the number of times playback should loop back from the
- * loop's end position to the loop's start position, or
- * {@link #LOOP_CONTINUOUSLY} to indicate that looping should
- * continue until interrupted
+ * @param count the number of times playback should loop back from the
+ * loop's end position to the loop's start position, or
+ * {@link #LOOP_CONTINUOUSLY} to indicate that looping should
+ * continue until interrupted
*/
- public void loop(int count);
+ void loop(int count);
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/CompoundControl.java
--- a/jdk/src/share/classes/javax/sound/sampled/CompoundControl.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/CompoundControl.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,55 +26,37 @@
package javax.sound.sampled;
/**
- * A CompoundControl, such as a graphic equalizer, provides control
- * over two or more related properties, each of which is itself represented as
- * a Control.
+ * A {@code CompoundControl}, such as a graphic equalizer, provides control over
+ * two or more related properties, each of which is itself represented as a
+ * {@code Control}.
*
* @author Kara Kytle
* @since 1.3
*/
public abstract class CompoundControl extends Control {
-
- // TYPE DEFINES
-
-
- // INSTANCE VARIABLES
-
-
/**
* The set of member controls.
*/
private Control[] controls;
-
-
- // CONSTRUCTORS
-
-
/**
* Constructs a new compound control object with the given parameters.
*
- * @param type the type of control represented this compound control object
- * @param memberControls the set of member controls
+ * @param type the type of control represented this compound control object
+ * @param memberControls the set of member controls
*/
protected CompoundControl(Type type, Control[] memberControls) {
-
super(type);
this.controls = memberControls;
}
-
-
- // METHODS
-
-
/**
* Returns the set of member controls that comprise the compound control.
- * @return the set of member controls.
+ *
+ * @return the set of member controls
*/
public Control[] getMemberControls() {
-
Control[] localArray = new Control[controls.length];
for (int i = 0; i < controls.length; i++) {
@@ -84,14 +66,12 @@
return localArray;
}
-
- // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
-
-
/**
- * Provides a string representation of the control
+ * Provides a string representation of the control.
+ *
* @return a string description
*/
+ @Override
public String toString() {
StringBuffer buf = new StringBuffer();
@@ -108,13 +88,9 @@
return new String(getType() + " Control containing " + buf + " Controls.");
}
-
- // INNER CLASSES
-
-
/**
- * An instance of the CompoundControl.Type inner class identifies one kind of
- * compound control. Static instances are provided for the
+ * An instance of the {@code CompoundControl.Type} inner class identifies
+ * one kind of compound control. Static instances are provided for the
* common types.
*
* @author Kara Kytle
@@ -122,19 +98,13 @@
*/
public static class Type extends Control.Type {
-
- // TYPE DEFINES
-
- // CONSTRUCTOR
-
-
/**
* Constructs a new compound control type.
- * @param name the name of the new compound control type
+ *
+ * @param name the name of the new compound control type
*/
- protected Type(String name) {
+ protected Type(final String name) {
super(name);
}
- } // class Type
-
-} // class CompoundControl
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/Control.java
--- a/jdk/src/share/classes/javax/sound/sampled/Control.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/Control.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,121 +26,102 @@
package javax.sound.sampled;
/**
- * {@link Line Lines} often have a set of controls, such as gain and pan, that affect
- * the audio signal passing through the line. Java Sound's Line objects
- * let you obtain a particular control object by passing its class as the
- * argument to a {@link Line#getControl(Control.Type) getControl} method.
+ * {@link Line Lines} often have a set of controls, such as gain and pan, that
+ * affect the audio signal passing through the line. Java Sound's {@code Line}
+ * objects let you obtain a particular control object by passing its class as
+ * the argument to a {@link Line#getControl(Control.Type) getControl} method.
*
* Because the various types of controls have different purposes and features,
- * all of their functionality is accessed from the subclasses that define
- * each kind of control.
+ * all of their functionality is accessed from the subclasses that define each
+ * kind of control.
*
* @author Kara Kytle
- *
* @see Line#getControls
* @see Line#isControlSupported
* @since 1.3
*/
public abstract class Control {
-
- // INSTANCE VARIABLES
-
/**
* The control type.
*/
private final Type type;
-
-
- // CONSTRUCTORS
-
/**
* Constructs a Control with the specified type.
- * @param type the kind of control desired
+ *
+ * @param type the kind of control desired
*/
protected Control(Type type) {
this.type = type;
}
-
- // METHODS
-
/**
* Obtains the control's type.
- * @return the control's type.
+ *
+ * @return the control's type
*/
public Type getType() {
return type;
}
-
- // ABSTRACT METHODS
-
/**
* Obtains a String describing the control type and its current state.
- * @return a String representation of the Control.
+ *
+ * @return a String representation of the Control
*/
+ @Override
public String toString() {
return new String(getType() + " Control");
}
-
/**
- * An instance of the Type class represents the type of
- * the control. Static instances are provided for the
- * common types.
+ * An instance of the {@code Type} class represents the type of the control.
+ * Static instances are provided for the common types.
*/
public static class Type {
- // CONTROL TYPE DEFINES
-
- // INSTANCE VARIABLES
-
/**
* Type name.
*/
private String name;
-
- // CONSTRUCTOR
-
/**
- * Constructs a new control type with the name specified.
- * The name should be a descriptive string appropriate for
- * labelling the control in an application, such as "Gain" or "Balance."
- * @param name the name of the new control type.
+ * Constructs a new control type with the name specified. The name
+ * should be a descriptive string appropriate for labelling the control
+ * in an application, such as "Gain" or "Balance".
+ *
+ * @param name the name of the new control type
*/
protected Type(String name) {
this.name = name;
}
-
- // METHODS
-
/**
- * Finalizes the equals method
+ * Finalizes the equals method.
*/
+ @Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
/**
- * Finalizes the hashCode method
+ * Finalizes the hashCode method.
*/
+ @Override
public final int hashCode() {
return super.hashCode();
}
/**
- * Provides the String representation of the control type. This String is
- * the same name that was passed to the constructor.
+ * Provides the {@code String} representation of the control type. This
+ * {@code String} is the same name that was passed to the constructor.
*
* @return the control type name
*/
+ @Override
public final String toString() {
return name;
}
- } // class Type
-
-} // class Control
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/DataLine.java
--- a/jdk/src/share/classes/javax/sound/sampled/DataLine.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/DataLine.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -28,40 +28,35 @@
import java.util.Arrays;
/**
- * DataLine adds media-related functionality to its
- * superinterface, {@link Line}. This functionality includes
- * transport-control methods that start, stop, drain, and flush
- * the audio data that passes through the line. A data line can also
- * report the current position, volume, and audio format of the media.
- * Data lines are used for output of audio by means of the
- * subinterfaces {@link SourceDataLine} or
- * {@link Clip}, which allow an application program to write data. Similarly,
- * audio input is handled by the subinterface {@link TargetDataLine},
- * which allows data to be read.
+ * {@code DataLine} adds media-related functionality to its superinterface,
+ * {@code Line}. This functionality includes transport-control methods that
+ * start, stop, drain, and flush the audio data that passes through the line. A
+ * data line can also report the current position, volume, and audio format of
+ * the media. Data lines are used for output of audio by means of the
+ * subinterfaces {@link SourceDataLine} or {@link Clip}, which allow an
+ * application program to write data. Similarly, audio input is handled by the
+ * subinterface {@link TargetDataLine}, which allows data to be read.
*
- * A data line has an internal buffer in which
- * the incoming or outgoing audio data is queued. The
- * {@link #drain()} method blocks until this internal buffer
- * becomes empty, usually because all queued data has been processed. The
- * {@link #flush()} method discards any available queued data
- * from the internal buffer.
+ * A data line has an internal buffer in which the incoming or outgoing audio
+ * data is queued. The {@link #drain()} method blocks until this internal buffer
+ * becomes empty, usually because all queued data has been processed. The
+ * {@link #flush()} method discards any available queued data from the internal
+ * buffer.
*
- * A data line produces {@link LineEvent.Type#START START} and
- * {@link LineEvent.Type#STOP STOP} events whenever
- * it begins or ceases active presentation or capture of data. These events
- * can be generated in response to specific requests, or as a result of
- * less direct state changes. For example, if {@link #start()} is called
- * on an inactive data line, and data is available for capture or playback, a
- * START event will be generated shortly, when data playback
- * or capture actually begins. Or, if the flow of data to an active data
- * line is constricted so that a gap occurs in the presentation of data,
- * a STOP event is generated.
+ * A data line produces {@link LineEvent.Type#START START} and
+ * {@link LineEvent.Type#STOP STOP} events whenever it begins or ceases active
+ * presentation or capture of data. These events can be generated in response to
+ * specific requests, or as a result of less direct state changes. For example,
+ * if {@link #start()} is called on an inactive data line, and data is available
+ * for capture or playback, a {@code START} event will be generated shortly,
+ * when data playback or capture actually begins. Or, if the flow of data to an
+ * active data line is constricted so that a gap occurs in the presentation of
+ * data, a {@code STOP} event is generated.
*
* Mixers often support synchronized control of multiple data lines.
* Synchronization can be established through the Mixer interface's
- * {@link Mixer#synchronize synchronize} method.
- * See the description of the {@link Mixer Mixer} interface
- * for a more complete description.
+ * {@link Mixer#synchronize synchronize} method. See the description of the
+ * {@link Mixer Mixer} interface for a more complete description.
*
* @author Kara Kytle
* @see LineEvent
@@ -69,220 +64,217 @@
*/
public interface DataLine extends Line {
-
/**
- * Drains queued data from the line by continuing data I/O until the
- * data line's internal buffer has been emptied.
- * This method blocks until the draining is complete. Because this is a
- * blocking method, it should be used with care. If drain()
- * is invoked on a stopped line that has data in its queue, the method will
- * block until the line is running and the data queue becomes empty. If
- * drain() is invoked by one thread, and another continues to
- * fill the data queue, the operation will not complete.
- * This method always returns when the data line is closed.
+ * Drains queued data from the line by continuing data I/O until the data
+ * line's internal buffer has been emptied. This method blocks until the
+ * draining is complete. Because this is a blocking method, it should be
+ * used with care. If {@code drain()} is invoked on a stopped line that has
+ * data in its queue, the method will block until the line is running and
+ * the data queue becomes empty. If {@code drain()} is invoked by one
+ * thread, and another continues to fill the data queue, the operation will
+ * not complete. This method always returns when the data line is closed.
*
* @see #flush()
*/
- public void drain();
+ void drain();
/**
- * Flushes queued data from the line. The flushed data is discarded.
- * In some cases, not all queued data can be discarded. For example, a
- * mixer can flush data from the buffer for a specific input line, but any
- * unplayed data already in the output buffer (the result of the mix) will
- * still be played. You can invoke this method after pausing a line (the
- * normal case) if you want to skip the "stale" data when you restart
- * playback or capture. (It is legal to flush a line that is not stopped,
- * but doing so on an active line is likely to cause a discontinuity in the
- * data, resulting in a perceptible click.)
+ * Flushes queued data from the line. The flushed data is discarded. In some
+ * cases, not all queued data can be discarded. For example, a mixer can
+ * flush data from the buffer for a specific input line, but any unplayed
+ * data already in the output buffer (the result of the mix) will still be
+ * played. You can invoke this method after pausing a line (the normal case)
+ * if you want to skip the "stale" data when you restart playback or
+ * capture. (It is legal to flush a line that is not stopped, but doing so
+ * on an active line is likely to cause a discontinuity in the data,
+ * resulting in a perceptible click.)
*
* @see #stop()
* @see #drain()
*/
- public void flush();
+ void flush();
/**
- * Allows a line to engage in data I/O. If invoked on a line
- * that is already running, this method does nothing. Unless the data in
- * the buffer has been flushed, the line resumes I/O starting
- * with the first frame that was unprocessed at the time the line was
- * stopped. When audio capture or playback starts, a
- * {@link LineEvent.Type#START START} event is generated.
+ * Allows a line to engage in data I/O. If invoked on a line that is already
+ * running, this method does nothing. Unless the data in the buffer has been
+ * flushed, the line resumes I/O starting with the first frame that was
+ * unprocessed at the time the line was stopped. When audio capture or
+ * playback starts, a {@link LineEvent.Type#START START} event is generated.
*
* @see #stop()
* @see #isRunning()
* @see LineEvent
*/
- public void start();
+ void start();
/**
- * Stops the line. A stopped line should cease I/O activity.
- * If the line is open and running, however, it should retain the resources required
- * to resume activity. A stopped line should retain any audio data in its buffer
- * instead of discarding it, so that upon resumption the I/O can continue where it left off,
- * if possible. (This doesn't guarantee that there will never be discontinuities beyond the
- * current buffer, of course; if the stopped condition continues
- * for too long, input or output samples might be dropped.) If desired, the retained data can be
- * discarded by invoking the flush method.
- * When audio capture or playback stops, a {@link LineEvent.Type#STOP STOP} event is generated.
+ * Stops the line. A stopped line should cease I/O activity. If the line is
+ * open and running, however, it should retain the resources required to
+ * resume activity. A stopped line should retain any audio data in its
+ * buffer instead of discarding it, so that upon resumption the I/O can
+ * continue where it left off, if possible. (This doesn't guarantee that
+ * there will never be discontinuities beyond the current buffer, of course;
+ * if the stopped condition continues for too long, input or output samples
+ * might be dropped.) If desired, the retained data can be discarded by
+ * invoking the {@code flush} method. When audio capture or playback stops,
+ * a {@link LineEvent.Type#STOP STOP} event is generated.
*
* @see #start()
* @see #isRunning()
* @see #flush()
* @see LineEvent
*/
- public void stop();
+ void stop();
/**
- * Indicates whether the line is running. The default is false.
- * An open line begins running when the first data is presented in response to an
- * invocation of the start method, and continues
- * until presentation ceases in response to a call to stop or
- * because playback completes.
- * @return true if the line is running, otherwise false
+ * Indicates whether the line is running. The default is {@code false}. An
+ * open line begins running when the first data is presented in response to
+ * an invocation of the {@code start} method, and continues until
+ * presentation ceases in response to a call to {@code stop} or because
+ * playback completes.
+ *
+ * @return {@code true} if the line is running, otherwise {@code false}
* @see #start()
* @see #stop()
*/
- public boolean isRunning();
+ boolean isRunning();
/**
- * Indicates whether the line is engaging in active I/O (such as playback
- * or capture). When an inactive line becomes active, it sends a
- * {@link LineEvent.Type#START START} event to its listeners. Similarly, when
- * an active line becomes inactive, it sends a
- * {@link LineEvent.Type#STOP STOP} event.
- * @return true if the line is actively capturing or rendering
- * sound, otherwise false
+ * Indicates whether the line is engaging in active I/O (such as playback or
+ * capture). When an inactive line becomes active, it sends a
+ * {@link LineEvent.Type#START START} event to its listeners. Similarly,
+ * when an active line becomes inactive, it sends a
+ * {@link LineEvent.Type#STOP STOP} event.
+ *
+ * @return {@code true} if the line is actively capturing or rendering
+ * sound, otherwise {@code false}
* @see #isOpen
* @see #addLineListener
* @see #removeLineListener
* @see LineEvent
* @see LineListener
*/
- public boolean isActive();
+ boolean isActive();
/**
* Obtains the current format (encoding, sample rate, number of channels,
* etc.) of the data line's audio data.
- *
- *
If the line is not open and has never been opened, it returns
- * the default format. The default format is an implementation
- * specific audio format, or, if the DataLine.Info
- * object, which was used to retrieve this DataLine,
- * specifies at least one fully qualified audio format, the
- * last one will be used as the default format. Opening the
- * line with a specific audio format (e.g.
- * {@link SourceDataLine#open(AudioFormat)}) will override the
- * default format.
+ *
+ * If the line is not open and has never been opened, it returns the default + * format. The default format is an implementation specific audio format, + * or, if the {@code DataLine.Info} object, which was used to retrieve this + * {@code DataLine}, specifies at least one fully qualified audio format, + * the last one will be used as the default format. Opening the line with a + * specific audio format (e.g. {@link SourceDataLine#open(AudioFormat)}) + * will override the default format. * * @return current audio data format * @see AudioFormat */ - public AudioFormat getFormat(); + AudioFormat getFormat(); /** - * Obtains the maximum number of bytes of data that will fit in the data line's - * internal buffer. For a source data line, this is the size of the buffer to - * which data can be written. For a target data line, it is the size of - * the buffer from which data can be read. Note that - * the units used are bytes, but will always correspond to an integral - * number of sample frames of audio data. + * Obtains the maximum number of bytes of data that will fit in the data + * line's internal buffer. For a source data line, this is the size of the + * buffer to which data can be written. For a target data line, it is the + * size of the buffer from which data can be read. Note that the units used + * are bytes, but will always correspond to an integral number of sample + * frames of audio data. * * @return the size of the buffer in bytes */ - public int getBufferSize(); + int getBufferSize(); /** * Obtains the number of bytes of data currently available to the - * application for processing in the data line's internal buffer. For a + * application for processing in the data line's internal buffer. For a * source data line, this is the amount of data that can be written to the - * buffer without blocking. For a target data line, this is the amount of data - * available to be read by the application. For a clip, this value is always - * 0 because the audio data is loaded into the buffer when the clip is opened, - * and persists without modification until the clip is closed. + * buffer without blocking. For a target data line, this is the amount of + * data available to be read by the application. For a clip, this value is + * always 0 because the audio data is loaded into the buffer when the clip + * is opened, and persists without modification until the clip is closed. *
- * Note that the units used are bytes, but will always - * correspond to an integral number of sample frames of audio data. + * Note that the units used are bytes, but will always correspond to an + * integral number of sample frames of audio data. *
- * An application is guaranteed that a read or
- * write operation of up to the number of bytes returned from
- * available() will not block; however, there is no guarantee
- * that attempts to read or write more data will block.
+ * An application is guaranteed that a read or write operation of up to the
+ * number of bytes returned from {@code available()} will not block;
+ * however, there is no guarantee that attempts to read or write more data
+ * will block.
*
* @return the amount of data available, in bytes
*/
- public int available();
+ int available();
/**
- * Obtains the current position in the audio data, in sample frames.
- * The frame position measures the number of sample
- * frames captured by, or rendered from, the line since it was opened.
- * This return value will wrap around after 2^31 frames. It is recommended
- * to use getLongFramePosition instead.
+ * Obtains the current position in the audio data, in sample frames. The
+ * frame position measures the number of sample frames captured by, or
+ * rendered from, the line since it was opened. This return value will wrap
+ * around after 2^31 frames. It is recommended to use
+ * {@code getLongFramePosition} instead.
*
* @return the number of frames already processed since the line was opened
* @see #getLongFramePosition()
*/
- public int getFramePosition();
-
+ int getFramePosition();
/**
- * Obtains the current position in the audio data, in sample frames.
- * The frame position measures the number of sample
- * frames captured by, or rendered from, the line since it was opened.
+ * Obtains the current position in the audio data, in sample frames. The
+ * frame position measures the number of sample frames captured by, or
+ * rendered from, the line since it was opened.
*
* @return the number of frames already processed since the line was opened
* @since 1.5
*/
- public long getLongFramePosition();
-
+ long getLongFramePosition();
/**
- * Obtains the current position in the audio data, in microseconds.
- * The microsecond position measures the time corresponding to the number
- * of sample frames captured by, or rendered from, the line since it was opened.
- * The level of precision is not guaranteed. For example, an implementation
- * might calculate the microsecond position from the current frame position
- * and the audio sample frame rate. The precision in microseconds would
- * then be limited to the number of microseconds per sample frame.
+ * Obtains the current position in the audio data, in microseconds. The
+ * microsecond position measures the time corresponding to the number of
+ * sample frames captured by, or rendered from, the line since it was
+ * opened. The level of precision is not guaranteed. For example, an
+ * implementation might calculate the microsecond position from the current
+ * frame position and the audio sample frame rate. The precision in
+ * microseconds would then be limited to the number of microseconds per
+ * sample frame.
*
- * @return the number of microseconds of data processed since the line was opened
+ * @return the number of microseconds of data processed since the line was
+ * opened
*/
- public long getMicrosecondPosition();
+ long getMicrosecondPosition();
/**
- * Obtains the current volume level for the line. This level is a measure
- * of the signal's current amplitude, and should not be confused with the
- * current setting of a gain control. The range is from 0.0 (silence) to
- * 1.0 (maximum possible amplitude for the sound waveform). The units
- * measure linear amplitude, not decibels.
+ * Obtains the current volume level for the line. This level is a measure of
+ * the signal's current amplitude, and should not be confused with the
+ * current setting of a gain control. The range is from 0.0 (silence) to 1.0
+ * (maximum possible amplitude for the sound waveform). The units measure
+ * linear amplitude, not decibels.
*
* @return the current amplitude of the signal in this line, or
- * {@link AudioSystem#NOT_SPECIFIED}
+ * {@link AudioSystem#NOT_SPECIFIED}
*/
- public float getLevel();
+ float getLevel();
/**
* Besides the class information inherited from its superclass,
- * DataLine.Info provides additional information specific to data lines.
- * This information includes:
+ * {@code DataLine.Info} provides additional information specific to data
+ * lines. This information includes:
*
Line.Info knows the class of the line its describes, a
- * DataLine.Info object can describe DataLine
- * subinterfaces such as {@link SourceDataLine},
- * {@link TargetDataLine}, and {@link Clip}.
- * You can query a mixer for lines of any of these types, passing an appropriate
- * instance of DataLine.Info as the argument to a method such as
- * {@link Mixer#getLine Mixer.getLine(Line.Info)}.
+ * Because a {@code Line.Info} knows the class of the line its describes, a
+ * {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
+ * such as {@link SourceDataLine}, {@link TargetDataLine}, and {@link Clip}.
+ * You can query a mixer for lines of any of these types, passing an
+ * appropriate instance of {@code DataLine.Info} as the argument to a method
+ * such as {@link Mixer#getLine(Line.Info)}.
*
* @see Line.Info
* @author Kara Kytle
* @since 1.3
*/
- public static class Info extends Line.Info {
+ class Info extends Line.Info {
private final AudioFormat[] formats;
private final int minBufferSize;
@@ -290,14 +282,17 @@
/**
* Constructs a data line's info object from the specified information,
- * which includes a set of supported audio formats and a range for the buffer size.
- * This constructor is typically used by mixer implementations
- * when returning information about a supported line.
+ * which includes a set of supported audio formats and a range for the
+ * buffer size. This constructor is typically used by mixer
+ * implementations when returning information about a supported line.
*
- * @param lineClass the class of the data line described by the info object
- * @param formats set of formats supported
- * @param minBufferSize minimum buffer size supported by the data line, in bytes
- * @param maxBufferSize maximum buffer size supported by the data line, in bytes
+ * @param lineClass the class of the data line described by the info
+ * object
+ * @param formats set of formats supported
+ * @param minBufferSize minimum buffer size supported by the data
+ * line, in bytes
+ * @param maxBufferSize maximum buffer size supported by the data
+ * line, in bytes
*/
public Info(Class lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
@@ -313,16 +308,16 @@
this.maxBufferSize = maxBufferSize;
}
-
/**
* Constructs a data line's info object from the specified information,
- * which includes a single audio format and a desired buffer size.
- * This constructor is typically used by an application to
- * describe a desired line.
+ * which includes a single audio format and a desired buffer size. This
+ * constructor is typically used by an application to describe a desired
+ * line.
*
- * @param lineClass the class of the data line described by the info object
- * @param format desired format
- * @param bufferSize desired buffer size in bytes
+ * @param lineClass the class of the data line described by the info
+ * object
+ * @param format desired format
+ * @param bufferSize desired buffer size in bytes
*/
public Info(Class lineClass, AudioFormat format, int bufferSize) {
@@ -338,39 +333,36 @@
this.maxBufferSize = bufferSize;
}
-
/**
* Constructs a data line's info object from the specified information,
- * which includes a single audio format.
- * This constructor is typically used by an application to
- * describe a desired line.
+ * which includes a single audio format. This constructor is typically
+ * used by an application to describe a desired line.
*
- * @param lineClass the class of the data line described by the info object
- * @param format desired format
+ * @param lineClass the class of the data line described by the info
+ * object
+ * @param format desired format
*/
public Info(Class lineClass, AudioFormat format) {
this(lineClass, format, AudioSystem.NOT_SPECIFIED);
}
-
/**
- * Obtains a set of audio formats supported by the data line.
- * Note that isFormatSupported(AudioFormat) might return
- * true for certain additional formats that are missing from
- * the set returned by getFormats(). The reverse is not
- * the case: isFormatSupported(AudioFormat) is guaranteed to return
- * true for all formats returned by getFormats().
- *
+ * Obtains a set of audio formats supported by the data line. Note that
+ * {@code isFormatSupported(AudioFormat)} might return {@code true} for
+ * certain additional formats that are missing from the set returned by
+ * {@code getFormats()}. The reverse is not the case:
+ * {@code isFormatSupported(AudioFormat)} is guaranteed to return
+ * {@code true} for all formats returned by {@code getFormats()}.
+ *
* Some fields in the AudioFormat instances can be set to
* {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED NOT_SPECIFIED}
- * if that field does not apply to the format,
- * or if the format supports a wide range of values for that field.
- * For example, a multi-channel device supporting up to
- * 64 channels, could set the channel field in the
- * AudioFormat instances returned by this
- * method to NOT_SPECIFIED.
+ * if that field does not apply to the format, or if the format supports
+ * a wide range of values for that field. For example, a multi-channel
+ * device supporting up to 64 channels, could set the channel field in
+ * the {@code AudioFormat} instances returned by this method to
+ * {@code NOT_SPECIFIED}.
*
- * @return a set of supported audio formats.
+ * @return a set of supported audio formats
* @see #isFormatSupported(AudioFormat)
*/
public AudioFormat[] getFormats() {
@@ -379,11 +371,12 @@
/**
* Indicates whether this data line supports a particular audio format.
- * The default implementation of this method simply returns true if
- * the specified format matches any of the supported formats.
+ * The default implementation of this method simply returns {@code true}
+ * if the specified format matches any of the supported formats.
*
- * @param format the audio format for which support is queried.
- * @return true if the format is supported, otherwise false
+ * @param format the audio format for which support is queried
+ * @return {@code true} if the format is supported, otherwise
+ * {@code false}
* @see #getFormats
* @see AudioFormat#matches
*/
@@ -400,32 +393,36 @@
/**
* Obtains the minimum buffer size supported by the data line.
- * @return minimum buffer size in bytes, or AudioSystem.NOT_SPECIFIED
+ *
+ * @return minimum buffer size in bytes, or
+ * {@code AudioSystem.NOT_SPECIFIED}
*/
public int getMinBufferSize() {
return minBufferSize;
}
-
/**
* Obtains the maximum buffer size supported by the data line.
- * @return maximum buffer size in bytes, or AudioSystem.NOT_SPECIFIED
+ *
+ * @return maximum buffer size in bytes, or
+ * {@code AudioSystem.NOT_SPECIFIED}
*/
public int getMaxBufferSize() {
return maxBufferSize;
}
-
/**
- * Determines whether the specified info object matches this one.
- * To match, the superclass match requirements must be met. In
- * addition, this object's minimum buffer size must be at least as
- * large as that of the object specified, its maximum buffer size must
- * be at most as large as that of the object specified, and all of its
- * formats must match formats supported by the object specified.
- * @return true if this object matches the one specified,
- * otherwise false.
+ * Determines whether the specified info object matches this one. To
+ * match, the superclass match requirements must be met. In addition,
+ * this object's minimum buffer size must be at least as large as that
+ * of the object specified, its maximum buffer size must be at most as
+ * large as that of the object specified, and all of its formats must
+ * match formats supported by the object specified.
+ *
+ * @return {@code true} if this object matches the one specified,
+ * otherwise {@code false}
*/
+ @Override
public boolean matches(Line.Info info) {
if (! (super.matches(info)) ) {
@@ -467,8 +464,10 @@
/**
* Obtains a textual description of the data line info.
+ *
* @return a string description
*/
+ @Override
public String toString() {
StringBuffer buf = new StringBuffer();
@@ -489,6 +488,5 @@
return new String(super.toString() + buf);
}
- } // class Info
-
-} // interface DataLine
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/EnumControl.java
--- a/jdk/src/share/classes/javax/sound/sampled/EnumControl.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/EnumControl.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,83 +26,63 @@
package javax.sound.sampled;
/**
- * A EnumControl provides control over a set of
- * discrete possible values, each represented by an object. In a
- * graphical user interface, such a control might be represented
- * by a set of buttons, each of which chooses one value or setting. For
- * example, a reverb control might provide several preset reverberation
- * settings, instead of providing continuously adjustable parameters
- * of the sort that would be represented by {@link FloatControl}
+ * A {@code EnumControl} provides control over a set of discrete possible values
+ * , each represented by an object. In a graphical user interface, such a
+ * control might be represented by a set of buttons, each of which chooses one
+ * value or setting. For example, a reverb control might provide several preset
+ * reverberation settings, instead of providing continuously adjustable
+ * parameters of the sort that would be represented by {@link FloatControl}
* objects.
*
- * Controls that provide a choice between only two settings can often be implemented
- * instead as a {@link BooleanControl}, and controls that provide
- * a set of values along some quantifiable dimension might be implemented
- * instead as a FloatControl with a coarse resolution.
- * However, a key feature of EnumControl is that the returned values
- * are arbitrary objects, rather than numerical or boolean values. This means that each
- * returned object can provide further information. As an example, the settings
- * of a {@link EnumControl.Type#REVERB REVERB} control are instances of
- * {@link ReverbType} that can be queried for the parameter values
- * used for each setting.
+ * Controls that provide a choice between only two settings can often be
+ * implemented instead as a {@link BooleanControl}, and controls that provide a
+ * set of values along some quantifiable dimension might be implemented instead
+ * as a {@code FloatControl} with a coarse resolution. However, a key feature of
+ * {@code EnumControl} is that the returned values are arbitrary objects, rather
+ * than numerical or boolean values. This means that each returned object can
+ * provide further information. As an example, the settings of a
+ * {@link EnumControl.Type#REVERB REVERB} control are instances of
+ * {@link ReverbType} that can be queried for the parameter values used for each
+ * setting.
*
* @author Kara Kytle
* @since 1.3
*/
public abstract class EnumControl extends Control {
-
- // TYPE DEFINES
-
-
- // INSTANCE VARIABLES
-
-
/**
* The set of possible values.
*/
private Object[] values;
-
/**
* The current value.
*/
private Object value;
-
-
- // CONSTRUCTORS
-
-
/**
* Constructs a new enumerated control object with the given parameters.
*
- * @param type the type of control represented this enumerated control object
- * @param values the set of possible values for the control
- * @param value the initial control value
+ * @param type the type of control represented this enumerated control
+ * object
+ * @param values the set of possible values for the control
+ * @param value the initial control value
*/
protected EnumControl(Type type, Object[] values, Object value) {
-
super(type);
-
this.values = values;
this.value = value;
}
-
-
- // METHODS
-
-
/**
- * Sets the current value for the control. The default implementation
- * simply sets the value as indicated. If the value indicated is not
- * supported, an IllegalArgumentException is thrown.
- * Some controls require that their line be open before they can be affected
- * by setting a value.
- * @param value the desired new value
+ * Sets the current value for the control. The default implementation simply
+ * sets the value as indicated. If the value indicated is not supported, an
+ * {@code IllegalArgumentException} is thrown. Some controls require that
+ * their line be open before they can be affected by setting a value.
+ *
+ * @param value the desired new value
* @throws IllegalArgumentException if the value indicated does not fall
- * within the allowable range
+ * within the allowable range
*/
public void setValue(Object value) {
if (!isValueSupported(value)) {
@@ -112,18 +92,18 @@
this.value = value;
}
-
/**
* Obtains this control's current value.
+ *
* @return the current value
*/
public Object getValue() {
return value;
}
-
/**
* Returns the set of possible values for this control.
+ *
* @return the set of possible values
*/
public Object[] getValues() {
@@ -137,12 +117,11 @@
return localArray;
}
-
/**
* Indicates whether the value specified is supported.
- * @param value the value for which support is queried
- * @return true if the value is supported,
- * otherwise false
+ *
+ * @param value the value for which support is queried
+ * @return {@code true} if the value is supported, otherwise {@code false}
*/
private boolean isValueSupported(Object value) {
@@ -157,58 +136,43 @@
return false;
}
-
-
- // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
-
-
/**
* Provides a string representation of the control.
+ *
* @return a string description
*/
+ @Override
public String toString() {
return new String(getType() + " with current value: " + getValue());
}
-
- // INNER CLASSES
-
-
/**
- * An instance of the EnumControl.Type inner class identifies one kind of
- * enumerated control. Static instances are provided for the
- * common types.
- *
- * @see EnumControl
+ * An instance of the {@code EnumControl.Type} inner class identifies one
+ * kind of enumerated control. Static instances are provided for the common
+ * types.
*
* @author Kara Kytle
+ * @see EnumControl
* @since 1.3
*/
public static class Type extends Control.Type {
-
- // TYPE DEFINES
-
/**
* Represents a control over a set of possible reverberation settings.
* Each reverberation setting is described by an instance of the
- * {@link ReverbType} class. (To access these settings,
- * invoke {@link EnumControl#getValues} on an
- * enumerated control of type REVERB.)
+ * {@link ReverbType} class. (To access these settings, invoke
+ * {@link EnumControl#getValues} on an enumerated control of type
+ * {@code REVERB}.)
*/
public static final Type REVERB = new Type("Reverb");
-
- // CONSTRUCTOR
-
-
/**
* Constructs a new enumerated control type.
- * @param name the name of the new enumerated control type
+ *
+ * @param name the name of the new enumerated control type
*/
- protected Type(String name) {
+ protected Type(final String name) {
super(name);
}
- } // class Type
-
-} // class EnumControl
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/FloatControl.java
--- a/jdk/src/share/classes/javax/sound/sampled/FloatControl.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/FloatControl.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,39 +26,31 @@
package javax.sound.sampled;
/**
- * A FloatControl object provides control over a range of
- * floating-point values. Float controls are often
- * represented in graphical user interfaces by continuously
- * adjustable objects such as sliders or rotary knobs. Concrete subclasses
- * of FloatControl implement controls, such as gain and pan, that
- * affect a line's audio signal in some way that an application can manipulate.
- * The {@link FloatControl.Type}
- * inner class provides static instances of types that are used to
- * identify some common kinds of float control.
+ * A {@code FloatControl} object provides control over a range of floating-point
+ * values. Float controls are often represented in graphical user interfaces by
+ * continuously adjustable objects such as sliders or rotary knobs. Concrete
+ * subclasses of {@code FloatControl} implement controls, such as gain and pan,
+ * that affect a line's audio signal in some way that an application can
+ * manipulate. The {@link FloatControl.Type} inner class provides static
+ * instances of types that are used to identify some common kinds of float
+ * control.
*
- * The FloatControl abstract class provides methods to set and get
- * the control's current floating-point value. Other methods obtain the possible
+ * The {@code FloatControl} abstract class provides methods to set and get the
+ * control's current floating-point value. Other methods obtain the possible
* range of values and the control's resolution (the smallest increment between
- * returned values). Some float controls allow ramping to a
- * new value over a specified period of time. FloatControl also
- * includes methods that return string labels for the minimum, maximum, and midpoint
- * positions of the control.
- *
- * @see Line#getControls
- * @see Line#isControlSupported
+ * returned values). Some float controls allow ramping to a new value over a
+ * specified period of time. {@code FloatControl} also includes methods that
+ * return string labels for the minimum, maximum, and midpoint positions of the
+ * control.
*
* @author David Rivas
* @author Kara Kytle
+ * @see Line#getControls
+ * @see Line#isControlSupported
* @since 1.3
*/
public abstract class FloatControl extends Control {
-
- // INSTANCE VARIABLES
-
-
- // FINAL VARIABLES
-
/**
* The minimum supported value.
*/
@@ -75,66 +67,60 @@
private float precision;
/**
- * The smallest time increment in which a value change
- * can be effected during a value shift, in microseconds.
+ * The smallest time increment in which a value change can be effected
+ * during a value shift, in microseconds.
*/
private int updatePeriod;
-
/**
- * A label for the units in which the control values are expressed,
- * such as "dB" for decibels.
+ * A label for the units in which the control values are expressed, such as
+ * "dB" for decibels.
*/
private final String units;
/**
- * A label for the minimum value, such as "Left."
+ * A label for the minimum value, such as "Left".
*/
private final String minLabel;
/**
- * A label for the maximum value, such as "Right."
+ * A label for the maximum value, such as "Right".
*/
private final String maxLabel;
/**
- * A label for the mid-point value, such as "Center."
+ * A label for the mid-point value, such as "Center".
*/
private final String midLabel;
-
- // STATE VARIABLES
-
/**
* The current value.
*/
private float value;
-
-
- // CONSTRUCTORS
-
-
/**
- * Constructs a new float control object with the given parameters
+ * Constructs a new float control object with the given parameters.
*
- * @param type the kind of control represented by this float control object
- * @param minimum the smallest value permitted for the control
- * @param maximum the largest value permitted for the control
- * @param precision the resolution or granularity of the control.
- * This is the size of the increment between discrete valid values.
- * @param updatePeriod the smallest time interval, in microseconds, over which the control
- * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
- * @param initialValue the value that the control starts with when constructed
- * @param units the label for the units in which the control's values are expressed,
- * such as "dB" or "frames per second"
- * @param minLabel the label for the minimum value, such as "Left" or "Off"
- * @param midLabel the label for the midpoint value, such as "Center" or "Default"
- * @param maxLabel the label for the maximum value, such as "Right" or "Full"
- *
- * @throws IllegalArgumentException if {@code minimum} is greater
- * than {@code maximum} or {@code initialValue} does not fall
- * within the allowable range
+ * @param type the kind of control represented by this float control object
+ * @param minimum the smallest value permitted for the control
+ * @param maximum the largest value permitted for the control
+ * @param precision the resolution or granularity of the control. This is
+ * the size of the increment between discrete valid values.
+ * @param updatePeriod the smallest time interval, in microseconds, over
+ * which the control can change from one discrete value to the next
+ * during a {@link #shift(float,float,int) shift}
+ * @param initialValue the value that the control starts with when
+ * constructed
+ * @param units the label for the units in which the control's values are
+ * expressed, such as "dB" or "frames per second"
+ * @param minLabel the label for the minimum value, such as "Left" or "Off"
+ * @param midLabel the label for the midpoint value, such as "Center" or
+ * "Default"
+ * @param maxLabel the label for the maximum value, such as "Right" or
+ * "Full"
+ * @throws IllegalArgumentException if {@code minimum} is greater than
+ * {@code maximum} or {@code initialValue} does not fall within the
+ * allowable range
*/
protected FloatControl(Type type, float minimum, float maximum,
float precision, int updatePeriod, float initialValue,
@@ -169,26 +155,26 @@
this.maxLabel = ( (maxLabel == null) ? "" : maxLabel);
}
-
/**
- * Constructs a new float control object with the given parameters.
- * The labels for the minimum, maximum, and mid-point values are set
- * to zero-length strings.
+ * Constructs a new float control object with the given parameters. The
+ * labels for the minimum, maximum, and mid-point values are set to
+ * zero-length strings.
*
- * @param type the kind of control represented by this float control object
- * @param minimum the smallest value permitted for the control
- * @param maximum the largest value permitted for the control
- * @param precision the resolution or granularity of the control.
- * This is the size of the increment between discrete valid values.
- * @param updatePeriod the smallest time interval, in microseconds, over which the control
- * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
- * @param initialValue the value that the control starts with when constructed
- * @param units the label for the units in which the control's values are expressed,
- * such as "dB" or "frames per second"
- *
- * @throws IllegalArgumentException if {@code minimum} is greater
- * than {@code maximum} or {@code initialValue} does not fall
- * within the allowable range
+ * @param type the kind of control represented by this float control object
+ * @param minimum the smallest value permitted for the control
+ * @param maximum the largest value permitted for the control
+ * @param precision the resolution or granularity of the control. This is
+ * the size of the increment between discrete valid values.
+ * @param updatePeriod the smallest time interval, in microseconds, over
+ * which the control can change from one discrete value to the next
+ * during a {@link #shift(float,float,int) shift}
+ * @param initialValue the value that the control starts with when
+ * constructed
+ * @param units the label for the units in which the control's values are
+ * expressed, such as "dB" or "frames per second"
+ * @throws IllegalArgumentException if {@code minimum} is greater than
+ * {@code maximum} or {@code initialValue} does not fall within the
+ * allowable range
*/
protected FloatControl(Type type, float minimum, float maximum,
float precision, int updatePeriod, float initialValue, String units) {
@@ -196,21 +182,16 @@
initialValue, units, "", "", "");
}
-
-
- // METHODS
-
-
/**
- * Sets the current value for the control. The default implementation
- * simply sets the value as indicated. If the value indicated is greater
- * than the maximum value, or smaller than the minimum value, an
- * IllegalArgumentException is thrown.
- * Some controls require that their line be open before they can be affected
- * by setting a value.
- * @param newValue desired new value
+ * Sets the current value for the control. The default implementation simply
+ * sets the value as indicated. If the value indicated is greater than the
+ * maximum value, or smaller than the minimum value, an
+ * {@code IllegalArgumentException} is thrown. Some controls require that
+ * their line be open before they can be affected by setting a value.
+ *
+ * @param newValue desired new value
* @throws IllegalArgumentException if the value indicated does not fall
- * within the allowable range
+ * within the allowable range
*/
public void setValue(float newValue) {
@@ -225,113 +206,114 @@
value = newValue;
}
-
/**
* Obtains this control's current value.
+ *
* @return the current value
*/
public float getValue() {
return value;
}
-
/**
* Obtains the maximum value permitted.
+ *
* @return the maximum allowable value
*/
public float getMaximum() {
return maximum;
}
-
/**
* Obtains the minimum value permitted.
+ *
* @return the minimum allowable value
*/
public float getMinimum() {
return minimum;
}
-
/**
- * Obtains the label for the units in which the control's values are expressed,
- * such as "dB" or "frames per second."
+ * Obtains the label for the units in which the control's values are
+ * expressed, such as "dB" or "frames per second."
+ *
* @return the units label, or a zero-length string if no label
*/
public String getUnits() {
return units;
}
-
/**
- * Obtains the label for the minimum value, such as "Left" or "Off."
- * @return the minimum value label, or a zero-length string if no label * has been set
+ * Obtains the label for the minimum value, such as "Left" or "Off".
+ *
+ * @return the minimum value label, or a zero-length string if no label has
+ * been set
*/
public String getMinLabel() {
return minLabel;
}
-
/**
- * Obtains the label for the mid-point value, such as "Center" or "Default."
- * @return the mid-point value label, or a zero-length string if no label * has been set
+ * Obtains the label for the mid-point value, such as "Center" or "Default".
+ *
+ * @return the mid-point value label, or a zero-length string if no label
+ * has been set
*/
public String getMidLabel() {
return midLabel;
}
-
/**
- * Obtains the label for the maximum value, such as "Right" or "Full."
- * @return the maximum value label, or a zero-length string if no label * has been set
+ * Obtains the label for the maximum value, such as "Right" or "Full".
+ *
+ * @return the maximum value label, or a zero-length string if no label has
+ * been set
*/
public String getMaxLabel() {
return maxLabel;
}
-
/**
- * Obtains the resolution or granularity of the control, in the units
- * that the control measures.
- * The precision is the size of the increment between discrete valid values
- * for this control, over the set of supported floating-point values.
+ * Obtains the resolution or granularity of the control, in the units that
+ * the control measures. The precision is the size of the increment between
+ * discrete valid values for this control, over the set of supported
+ * floating-point values.
+ *
* @return the control's precision
*/
public float getPrecision() {
return precision;
}
-
/**
- * Obtains the smallest time interval, in microseconds, over which the control's value can
- * change during a shift. The update period is the inverse of the frequency with which
- * the control updates its value during a shift. If the implementation does not support value shifting over
- * time, it should set the control's value to the final value immediately
- * and return -1 from this method.
+ * Obtains the smallest time interval, in microseconds, over which the
+ * control's value can change during a shift. The update period is the
+ * inverse of the frequency with which the control updates its value during
+ * a shift. If the implementation does not support value shifting over time,
+ * it should set the control's value to the final value immediately and
+ * return -1 from this method.
*
- * @return update period in microseconds, or -1 if shifting over time is unsupported
+ * @return update period in microseconds, or -1 if shifting over time is
+ * unsupported
* @see #shift
*/
public int getUpdatePeriod() {
return updatePeriod;
}
-
/**
- * Changes the control value from the initial value to the final
- * value linearly over the specified time period, specified in microseconds.
- * This method returns without blocking; it does not wait for the shift
- * to complete. An implementation should complete the operation within the time
- * specified. The default implementation simply changes the value
- * to the final value immediately.
+ * Changes the control value from the initial value to the final value
+ * linearly over the specified time period, specified in microseconds. This
+ * method returns without blocking; it does not wait for the shift to
+ * complete. An implementation should complete the operation within the time
+ * specified. The default implementation simply changes the value to the
+ * final value immediately.
*
- * @param from initial value at the beginning of the shift
- * @param to final value after the shift
- * @param microseconds maximum duration of the shift in microseconds
- *
+ * @param from initial value at the beginning of the shift
+ * @param to final value after the shift
+ * @param microseconds maximum duration of the shift in microseconds
* @throws IllegalArgumentException if either {@code from} or {@code to}
- * value does not fall within the allowable range
- *
+ * value does not fall within the allowable range
* @see #getUpdatePeriod
*/
public void shift(float from, float to, int microseconds) {
@@ -347,12 +329,9 @@
setValue(to);
}
-
- // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
-
-
/**
- * Provides a string representation of the control
+ * Provides a string representation of the control.
+ *
* @return a string description
*/
public String toString() {
@@ -360,55 +339,45 @@
" (range: " + minimum + " - " + maximum + ")");
}
-
- // INNER CLASSES
-
-
/**
- * An instance of the FloatControl.Type inner class identifies one kind of
- * float control. Static instances are provided for the
- * common types.
+ * An instance of the {@code FloatControl.Type} inner class identifies one
+ * kind of float control. Static instances are provided for the common
+ * types.
*
* @author Kara Kytle
* @since 1.3
*/
public static class Type extends Control.Type {
-
- // TYPE DEFINES
-
-
- // GAIN TYPES
-
/**
* Represents a control for the overall gain on a line.
*
* Gain is a quantity in decibels (dB) that is added to the intrinsic - * decibel level of the audio signal--that is, the level of - * the signal before it is altered by the gain control. A positive - * gain amplifies (boosts) the signal's volume, and a negative gain - * attenuates (cuts) it. + * decibel level of the audio signal--that is, the level of the signal + * before it is altered by the gain control. A positive gain amplifies + * (boosts) the signal's volume, and a negative gain attenuates(cuts)it. * The gain setting defaults to a value of 0.0 dB, meaning the signal's - * loudness is unaffected. Note that gain measures dB, not amplitude. + * loudness is unaffected. Note that gain measures dB, not amplitude. * The relationship between a gain in decibels and the corresponding * linear amplitude multiplier is: * - *
linearScalar = pow(10.0, gainDB/20.0)
- * The FloatControl class has methods to impose a maximum and
- * minimum allowable value for gain. However, because an audio signal might
- * already be at a high amplitude, the maximum setting does not guarantee
- * that the signal will be undistorted when the gain is applied to it (unless
- * the maximum is zero or negative). To avoid numeric overflow from excessively
- * large gain settings, a gain control can implement
- * clipping, meaning that the signal's amplitude will be limited to the maximum
- * value representable by its audio format, instead of wrapping around.
+ * The {@code FloatControl} class has methods to impose a maximum and
+ * minimum allowable value for gain. However, because an audio signal
+ * might already be at a high amplitude, the maximum setting does not
+ * guarantee that the signal will be undistorted when the gain is
+ * applied to it (unless the maximum is zero or negative). To avoid
+ * numeric overflow from excessively large gain settings, a gain control
+ * can implement clipping, meaning that the signal's amplitude will be
+ * limited to the maximum value representable by its audio format,
+ * instead of wrapping around.
*
- * These comments apply to gain controls in general, not just master gain controls.
- * A line can have more than one gain control. For example, a mixer (which is
- * itself a line) might have a master gain control, an auxiliary return control,
- * a reverb return control, and, on each of its source lines, an individual aux
- * send and reverb send.
+ * These comments apply to gain controls in general, not just master
+ * gain controls. A line can have more than one gain control. For
+ * example, a mixer (which is itself a line) might have a master gain
+ * control, an auxiliary return control, a reverb return control, and,
+ * on each of its source lines, an individual aux send and reverb send.
*
* @see #AUX_SEND
* @see #AUX_RETURN
@@ -435,9 +404,9 @@
public static final Type AUX_RETURN = new Type("AUX Return");
/**
- * Represents a control for the pre-reverb gain on a line.
- * This control may be used to affect how much
- * of a line's signal is directed to a mixer's internal reverberation unit.
+ * Represents a control for the pre-reverb gain on a line. This control
+ * may be used to affect how much of a line's signal is directed to a
+ * mixer's internal reverberation unit.
*
* @see #MASTER_GAIN
* @see #REVERB_RETURN
@@ -446,18 +415,15 @@
public static final Type REVERB_SEND = new Type("Reverb Send");
/**
- * Represents a control for the post-reverb gain on a line.
- * This control may be used to control the relative amplitude
- * of the signal returned from an internal reverberation unit.
+ * Represents a control for the post-reverb gain on a line. This control
+ * may be used to control the relative amplitude of the signal returned
+ * from an internal reverberation unit.
*
* @see #MASTER_GAIN
* @see #REVERB_SEND
*/
public static final Type REVERB_RETURN = new Type("Reverb Return");
-
- // VOLUME
-
/**
* Represents a control for the volume on a line.
*/
@@ -466,64 +432,52 @@
*/
public static final Type VOLUME = new Type("Volume");
-
- // PAN
-
/**
- * Represents a control for the relative pan (left-right positioning)
- * of the signal. The signal may be mono; the pan setting affects how
- * it is distributed by the mixer in a stereo mix. The valid range of values is -1.0
- * (left channel only) to 1.0 (right channel
- * only). The default is 0.0 (centered).
+ * Represents a control for the relative pan (left-right positioning) of
+ * the signal. The signal may be mono; the pan setting affects how it is
+ * distributed by the mixer in a stereo mix. The valid range of values
+ * is -1.0 (left channel only) to 1.0 (right channel only). The default
+ * is 0.0 (centered).
*
* @see #BALANCE
*/
public static final Type PAN = new Type("Pan");
-
- // BALANCE
-
/**
* Represents a control for the relative balance of a stereo signal
- * between two stereo speakers. The valid range of values is -1.0 (left channel only) to 1.0 (right channel
- * only). The default is 0.0 (centered).
+ * between two stereo speakers. The valid range of values is -1.0 (left
+ * channel only) to 1.0 (right channel only). The default is 0.0
+ * (centered).
*
* @see #PAN
*/
public static final Type BALANCE = new Type("Balance");
-
- // SAMPLE RATE
-
/**
- * Represents a control that changes the sample rate of audio playback. The net effect
- * of changing the sample rate depends on the relationship between
- * the media's natural rate and the rate that is set via this control.
- * The natural rate is the sample rate that is specified in the data line's
- * AudioFormat object. For example, if the natural rate
- * of the media is 11025 samples per second and the sample rate is set
- * to 22050 samples per second, the media will play back at twice the
- * normal speed.
+ * Represents a control that changes the sample rate of audio playback.
+ * The net effect of changing the sample rate depends on the
+ * relationship between the media's natural rate and the rate that is
+ * set via this control. The natural rate is the sample rate that is
+ * specified in the data line's {@code AudioFormat} object. For example,
+ * if the natural rate of the media is 11025 samples per second and the
+ * sample rate is set to 22050 samples per second, the media will play
+ * back at twice the normal speed.
*
- * Changing the sample rate with this control does not affect the data line's
- * audio format. Also note that whenever you change a sound's sample rate, a
- * change in the sound's pitch results. For example, doubling the sample
- * rate has the effect of doubling the frequencies in the sound's spectrum,
- * which raises the pitch by an octave.
+ * Changing the sample rate with this control does not affect the data
+ * line's audio format. Also note that whenever you change a sound's
+ * sample rate, a change in the sound's pitch results. For example,
+ * doubling the sample rate has the effect of doubling the frequencies
+ * in the sound's spectrum, which raises the pitch by an octave.
*/
public static final Type SAMPLE_RATE = new Type("Sample Rate");
-
- // CONSTRUCTOR
-
/**
* Constructs a new float control type.
- * @param name the name of the new float control type
+ *
+ * @param name the name of the new float control type
*/
- protected Type(String name) {
+ protected Type(final String name) {
super(name);
}
-
- } // class Type
-
-} // class FloatControl
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/Line.java
--- a/jdk/src/share/classes/javax/sound/sampled/Line.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/Line.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,96 +26,90 @@
package javax.sound.sampled;
/**
- * The Line interface represents a mono or multi-channel
- * audio feed. A line is an element of the digital audio
- * "pipeline," such as a mixer, an input or output port,
- * or a data path into or out of a mixer.
+ * The {@code Line} interface represents a mono or multi-channel audio feed. A
+ * line is an element of the digital audio "pipeline," such as a mixer, an input
+ * or output port, or a data path into or out of a mixer.
*
- * A line can have controls, such as gain, pan, and reverb.
- * The controls themselves are instances of classes that extend the
- * base {@link Control} class.
- * The Line interface provides two accessor methods for
- * obtaining the line's controls: {@link #getControls getControls} returns the
- * entire set, and {@link #getControl getControl} returns a single control of
- * specified type.
+ * A line can have controls, such as gain, pan, and reverb. The controls
+ * themselves are instances of classes that extend the base {@link Control}
+ * class. The {@code Line} interface provides two accessor methods for obtaining
+ * the line's controls: {@link #getControls getControls} returns the entire set,
+ * and {@link #getControl getControl} returns a single control of specified
+ * type.
*
- * Lines exist in various states at different times. When a line opens, it reserves system
- * resources for itself, and when it closes, these resources are freed for
- * other objects or applications. The {@link #isOpen()} method lets
- * you discover whether a line is open or closed.
- * An open line need not be processing data, however. Such processing is
- * typically initiated by subinterface methods such as
- * {@link SourceDataLine#write SourceDataLine.write} and
- * {@link TargetDataLine#read TargetDataLine.read}.
- *
- * You can register an object to receive notifications whenever the line's
- * state changes. The object must implement the {@link LineListener}
- * interface, which consists of the single method
- * {@link LineListener#update update}.
- * This method will be invoked when a line opens and closes (and, if it's a
- * {@link DataLine}, when it starts and stops).
- *
- * An object can be registered to listen to multiple lines. The event it
- * receives in its update method will specify which line created
- * the event, what type of event it was
- * (OPEN, CLOSE, START, or STOP),
- * and how many sample frames the line had processed at the time the event occurred.
+ * Lines exist in various states at different times. When a line opens, it
+ * reserves system resources for itself, and when it closes, these resources are
+ * freed for other objects or applications. The {@link #isOpen()} method lets
+ * you discover whether a line is open or closed. An open line need not be
+ * processing data, however. Such processing is typically initiated by
+ * subinterface methods such as
+ * {@link SourceDataLine#write SourceDataLine.write} and
+ * {@link TargetDataLine#read TargetDataLine.read}.
+ *
+ * You can register an object to receive notifications whenever the line's state + * changes. The object must implement the {@link LineListener} interface, which + * consists of the single method {@link LineListener#update update}. This method + * will be invoked when a line opens and closes (and, if it's a {@link DataLine} + * , when it starts and stops). + *
+ * An object can be registered to listen to multiple lines. The event it + * receives in its {@code update} method will specify which line created the + * event, what type of event it was ({@code OPEN}, {@code CLOSE}, {@code START}, + * or {@code STOP}), and how many sample frames the line had processed at the + * time the event occurred. *
* Certain line operations, such as open and close, can generate security
* exceptions if invoked by unprivileged code when the line is a shared audio
* resource.
*
* @author Kara Kytle
- *
* @see LineEvent
* @since 1.3
*/
public interface Line extends AutoCloseable {
/**
- * Obtains the Line.Info object describing this
- * line.
+ * Obtains the {@code Line.Info} object describing this line.
+ *
* @return description of the line
*/
- public Line.Info getLineInfo();
+ Line.Info getLineInfo();
/**
- * Opens the line, indicating that it should acquire any required
- * system resources and become operational.
- * If this operation
- * succeeds, the line is marked as open, and an OPEN event is dispatched
- * to the line's listeners.
+ * Opens the line, indicating that it should acquire any required system
+ * resources and become operational. If this operation succeeds, the line is
+ * marked as open, and an {@code OPEN} event is dispatched to the line's
+ * listeners.
*
- * Note that some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in an LineUnavailableException.
+ * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+ * such a line will always result in an {@code LineUnavailableException}.
*
- * Some types of lines have configurable properties that may affect
- * resource allocation. For example, a DataLine must
- * be opened with a particular format and buffer size. Such lines
- * should provide a mechanism for configuring these properties, such
- * as an additional open method or methods which allow
- * an application to specify the desired settings.
+ * Some types of lines have configurable properties that may affect resource
+ * allocation. For example, a {@code DataLine} must be opened with a
+ * particular format and buffer size. Such lines should provide a mechanism
+ * for configuring these properties, such as an additional {@code open}
+ * method or methods which allow an application to specify the desired
+ * settings.
*
* This method takes no arguments, and opens the line with the current
- * settings. For {@link SourceDataLine} and
- * {@link TargetDataLine} objects, this means that the line is
- * opened with default settings. For a {@link Clip}, however,
- * the buffer size is determined when data is loaded. Since this method does not
- * allow the application to specify any data to load, an IllegalArgumentException
- * is thrown. Therefore, you should instead use one of the open methods
- * provided in the Clip interface to load data into the Clip.
+ * settings. For {@link SourceDataLine} and {@link TargetDataLine} objects,
+ * this means that the line is opened with default settings. For a
+ * {@link Clip}, however, the buffer size is determined when data is loaded.
+ * Since this method does not allow the application to specify any data to
+ * load, an {@code IllegalArgumentException} is thrown. Therefore, you
+ * should instead use one of the {@code open} methods provided in the
+ * {@code Clip} interface to load data into the {@code Clip}.
*
- * For DataLine's, if the DataLine.Info
- * object which was used to retrieve the line, specifies at least
- * one fully qualified audio format, the last one will be used
- * as the default format.
+ * For {@code DataLine}'s, if the {@code DataLine.Info} object which was
+ * used to retrieve the line, specifies at least one fully qualified audio
+ * format, the last one will be used as the default format.
*
- * @throws IllegalArgumentException if this method is called on a Clip instance.
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions.
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions.
- *
+ * @throws IllegalArgumentException if this method is called on a Clip
+ * instance
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #close
* @see #isOpen
* @see LineEvent
@@ -123,133 +117,128 @@
* @see Clip#open(AudioFormat, byte[], int, int)
* @see Clip#open(AudioInputStream)
*/
- public void open() throws LineUnavailableException;
-
+ void open() throws LineUnavailableException;
/**
- * Closes the line, indicating that any system resources
- * in use by the line can be released. If this operation
- * succeeds, the line is marked closed and a CLOSE event is dispatched
- * to the line's listeners.
- * @throws SecurityException if the line cannot be
- * closed due to security restrictions.
+ * Closes the line, indicating that any system resources in use by the line
+ * can be released. If this operation succeeds, the line is marked closed
+ * and a {@code CLOSE} event is dispatched to the line's listeners.
*
+ * @throws SecurityException if the line cannot be closed due to security
+ * restrictions
* @see #open
* @see #isOpen
* @see LineEvent
*/
- public void close();
-
-
+ @Override
+ void close();
/**
- * Indicates whether the line is open, meaning that it has reserved
- * system resources and is operational, although it might not currently be
- * playing or capturing sound.
- * @return true if the line is open, otherwise false
+ * Indicates whether the line is open, meaning that it has reserved system
+ * resources and is operational, although it might not currently be playing
+ * or capturing sound.
*
+ * @return {@code true} if the line is open, otherwise {@code false}
* @see #open()
* @see #close()
*/
- public boolean isOpen();
-
+ boolean isOpen();
/**
- * Obtains the set of controls associated with this line.
- * Some controls may only be available when the line is open.
- * If there are no controls, this method returns an array of length 0.
+ * Obtains the set of controls associated with this line. Some controls may
+ * only be available when the line is open. If there are no controls, this
+ * method returns an array of length 0.
+ *
* @return the array of controls
* @see #getControl
*/
- public Control[] getControls();
+ Control[] getControls();
/**
- * Indicates whether the line supports a control of the specified type.
- * Some controls may only be available when the line is open.
- * @param control the type of the control for which support is queried
- * @return true if at least one control of the specified type is
- * supported, otherwise false.
+ * Indicates whether the line supports a control of the specified type. Some
+ * controls may only be available when the line is open.
+ *
+ * @param control the type of the control for which support is queried
+ * @return {@code true} if at least one control of the specified type is
+ * supported, otherwise {@code false}
*/
- public boolean isControlSupported(Control.Type control);
-
+ boolean isControlSupported(Control.Type control);
/**
- * Obtains a control of the specified type,
- * if there is any.
- * Some controls may only be available when the line is open.
- * @param control the type of the requested control
+ * Obtains a control of the specified type, if there is any. Some controls
+ * may only be available when the line is open.
+ *
+ * @param control the type of the requested control
* @return a control of the specified type
- * @throws IllegalArgumentException if a control of the specified type
- * is not supported
+ * @throws IllegalArgumentException if a control of the specified type is
+ * not supported
* @see #getControls
* @see #isControlSupported(Control.Type control)
*/
- public Control getControl(Control.Type control);
-
+ Control getControl(Control.Type control);
/**
- * Adds a listener to this line. Whenever the line's status changes, the
- * listener's update() method is called with a LineEvent object
- * that describes the change.
- * @param listener the object to add as a listener to this line
+ * Adds a listener to this line. Whenever the line's status changes, the
+ * listener's {@code update()} method is called with a {@code LineEvent}
+ * object that describes the change.
+ *
+ * @param listener the object to add as a listener to this line
* @see #removeLineListener
* @see LineListener#update
* @see LineEvent
*/
- public void addLineListener(LineListener listener);
-
+ void addLineListener(LineListener listener);
/**
* Removes the specified listener from this line's list of listeners.
- * @param listener listener to remove
+ *
+ * @param listener listener to remove
* @see #addLineListener
*/
- public void removeLineListener(LineListener listener);
-
+ void removeLineListener(LineListener listener);
/**
- * A Line.Info object contains information about a line.
- * The only information provided by Line.Info itself
- * is the Java class of the line.
- * A subclass of Line.Info adds other kinds of information
- * about the line. This additional information depends on which Line
- * subinterface is implemented by the kind of line that the Line.Info
- * subclass describes.
+ * A {@code Line.Info} object contains information about a line. The only
+ * information provided by {@code Line.Info} itself is the Java class of the
+ * line. A subclass of {@code Line.Info} adds other kinds of information
+ * about the line. This additional information depends on which {@code Line}
+ * subinterface is implemented by the kind of line that the
+ * {@code Line.Info} subclass describes.
*
- * A Line.Info can be retrieved using various methods of
- * the Line, Mixer, and AudioSystem
- * interfaces. Other such methods let you pass a Line.Info as
- * an argument, to learn whether lines matching the specified configuration
- * are available and to obtain them.
+ * A {@code Line.Info} can be retrieved using various methods of the
+ * {@code Line}, {@code Mixer}, and {@code AudioSystem} interfaces. Other
+ * such methods let you pass a {@code Line.Info} as an argument, to learn
+ * whether lines matching the specified configuration are available and to
+ * obtain them.
*
* @author Kara Kytle
- *
- * @see Line#getLineInfo
- * @see Mixer#getSourceLineInfo
- * @see Mixer#getTargetLineInfo
- * @see Mixer#getLine Mixer.getLine(Line.Info)
- * @see Mixer#getSourceLineInfo(Line.Info) Mixer.getSourceLineInfo(Line.Info)
- * @see Mixer#getSourceLineInfo(Line.Info) Mixer.getTargetLineInfo(Line.Info)
- * @see Mixer#isLineSupported Mixer.isLineSupported(Line.Info)
- * @see AudioSystem#getLine AudioSystem.getLine(Line.Info)
- * @see AudioSystem#getSourceLineInfo AudioSystem.getSourceLineInfo(Line.Info)
- * @see AudioSystem#getTargetLineInfo AudioSystem.getTargetLineInfo(Line.Info)
- * @see AudioSystem#isLineSupported AudioSystem.isLineSupported(Line.Info)
+ * @see Line#getLineInfo()
+ * @see Mixer#getSourceLineInfo()
+ * @see Mixer#getTargetLineInfo()
+ * @see Mixer#getLine(Line.Info)
+ * @see Mixer#getSourceLineInfo(Line.Info)
+ * @see Mixer#getTargetLineInfo(Line.Info)
+ * @see Mixer#isLineSupported(Line.Info)
+ * @see AudioSystem#getLine(Line.Info)
+ * @see AudioSystem#getSourceLineInfo(Line.Info)
+ * @see AudioSystem#getTargetLineInfo(Line.Info)
+ * @see AudioSystem#isLineSupported(Line.Info)
* @since 1.3
*/
- public static class Info {
+ class Info {
/**
* The class of the line described by the info object.
*/
private final Class lineClass;
-
/**
- * Constructs an info object that describes a line of the specified class.
- * This constructor is typically used by an application to
+ * Constructs an info object that describes a line of the specified
+ * class. This constructor is typically used by an application to
* describe a desired line.
- * @param lineClass the class of the line that the new Line.Info object describes
+ *
+ * @param lineClass the class of the line that the new Line.Info object
+ * describes
*/
public Info(Class lineClass) {
@@ -260,33 +249,29 @@
}
}
-
-
/**
* Obtains the class of the line that this Line.Info object describes.
+ *
* @return the described line's class
*/
public Class getLineClass() {
return lineClass;
}
-
/**
- * Indicates whether the specified info object matches this one.
- * To match, the specified object must be identical to or
- * a special case of this one. The specified info object
- * must be either an instance of the same class as this one,
- * or an instance of a sub-type of this one. In addition, the
- * attributes of the specified object must be compatible with the
- * capabilities of this one. Specifically, the routing configuration
- * for the specified info object must be compatible with that of this
- * one.
- * Subclasses may add other criteria to determine whether the two objects
- * match.
+ * Indicates whether the specified info object matches this one. To
+ * match, the specified object must be identical to or a special case of
+ * this one. The specified info object must be either an instance of
+ * the same class as this one, or an instance of a sub-type of this one.
+ * In addition, the attributes of the specified object must be
+ * compatible with the capabilities of this one. Specifically, the
+ * routing configuration for the specified info object must be
+ * compatible with that of this one. Subclasses may add other criteria
+ * to determine whether the two objects match.
*
- * @param info the info object which is being compared to this one
- * @return true if the specified object matches this one,
- * false otherwise
+ * @param info the info object which is being compared to this one
+ * @return {@code true} if the specified object matches this one,
+ * {@code false} otherwise
*/
public boolean matches(Info info) {
@@ -320,7 +305,6 @@
return false;
}
-
// this.isAssignableFrom(that) => this is same or super to that
// => this is at least as general as that
// => that may be subtype of this
@@ -332,11 +316,12 @@
return true;
}
-
/**
* Obtains a textual description of the line info.
+ *
* @return a string description
*/
+ @Override
public String toString() {
String fullPackagePath = "javax.sound.sampled.";
@@ -353,7 +338,5 @@
return finalString;
}
-
- } // class Info
-
-} // interface Line
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/LineEvent.java
--- a/jdk/src/share/classes/javax/sound/sampled/LineEvent.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/LineEvent.java Wed Jun 04 17:14:56 2014 +0400
@@ -25,61 +25,64 @@
package javax.sound.sampled;
+import java.util.EventObject;
+
/**
- * The LineEvent class encapsulates information that a line
- * sends its listeners whenever the line opens, closes, starts, or stops.
- * Each of these four state changes is represented by a corresponding
- * type of event. A listener receives the event as a parameter to its
- * {@link LineListener#update update} method. By querying the event,
- * the listener can learn the type of event, the line responsible for
- * the event, and how much data the line had processed when the event occurred.
- *
- *
Although this class implements Serializable, attempts to
- * serialize a LineEvent object will fail.
+ * The {@code LineEvent} class encapsulates information that a line sends its
+ * listeners whenever the line opens, closes, starts, or stops. Each of these
+ * four state changes is represented by a corresponding type of event. A
+ * listener receives the event as a parameter to its
+ * {@link LineListener#update update} method. By querying the event, the
+ * listener can learn the type of event, the line responsible for the event, and
+ * how much data the line had processed when the event occurred.
+ *
+ * Although this class implements Serializable, attempts to serialize a
+ * {@code LineEvent} object will fail.
*
* @author Kara Kytle
- *
* @see Line
* @see LineListener#update
* @since 1.3
*
* @serial exclude
*/
-public class LineEvent extends java.util.EventObject {
+public class LineEvent extends EventObject {
+
private static final long serialVersionUID = -1274246333383880410L;
- // INSTANCE VARIABLES
-
/**
- * The kind of line event (OPEN, CLOSE,
- * START, or STOP).
+ * The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
+ * {@code STOP}).
+ *
+ * @serial
* @see #getType
- * @serial
*/
private final Type type;
/**
* The media position when the event occurred, expressed in sample frames.
- * Note that this field is only relevant to certain events generated by
- * data lines, such as START and STOP. For
- * events generated by lines that do not count sample frames, and for any
- * other events for which this value is not known, the position value
- * should be {@link AudioSystem#NOT_SPECIFIED}.
+ * Note that this field is only relevant to certain events generated by data
+ * lines, such as {@code START} and {@code STOP}. For events generated by
+ * lines that do not count sample frames, and for any other events for which
+ * this value is not known, the position value should be
+ * {@link AudioSystem#NOT_SPECIFIED}.
+ *
* @serial
* @see #getFramePosition
*/
private final long position;
-
/**
- * Constructs a new event of the specified type, originating from the specified line.
- * @param line the source of this event
- * @param type the event type (OPEN, CLOSE, START, or STOP)
- * @param position the number of sample frames that the line had already processed when the event occurred,
- * or {@link AudioSystem#NOT_SPECIFIED}
+ * Constructs a new event of the specified type, originating from the
+ * specified line.
*
- * @throws IllegalArgumentException if line is
- * null.
+ * @param line the source of this event
+ * @param type the event type ({@code OPEN}, {@code CLOSE}, {@code START},
+ * or {@code STOP})
+ * @param position the number of sample frames that the line had already
+ * processed when the event occurred, or
+ * {@link AudioSystem#NOT_SPECIFIED}
+ * @throws IllegalArgumentException if {@code line} is {@code null}.
*/
public LineEvent(Line line, Type type, long position) {
@@ -90,6 +93,7 @@
/**
* Obtains the audio line that is the source of this event.
+ *
* @return the line responsible for this event
*/
public final Line getLine() {
@@ -97,11 +101,11 @@
return (Line)getSource();
}
-
/**
* Obtains the event's type.
+ *
* @return this event's type ({@link Type#OPEN}, {@link Type#CLOSE},
- * {@link Type#START}, or {@link Type#STOP})
+ * {@link Type#START}, or {@link Type#STOP})
*/
public final Type getType() {
@@ -109,21 +113,24 @@
}
/**
- * Obtains the position in the line's audio data when the event occurred, expressed in sample frames.
- * For example, if a source line had already played back 14 sample frames at the time it was
- * paused, the pause event would report the line's position as 14. The next frame to be processed
- * would be frame number 14 using zero-based numbering, or 15 using one-based numbering.
+ * Obtains the position in the line's audio data when the event occurred,
+ * expressed in sample frames. For example, if a source line had already
+ * played back 14 sample frames at the time it was paused, the pause event
+ * would report the line's position as 14. The next frame to be processed
+ * would be frame number 14 using zero-based numbering, or 15 using
+ * one-based numbering.
*
- * Note that this field is relevant only to certain events generated by
- * data lines, such as START and STOP. For
- * events generated by lines that do not count sample frames, and for any
- * other events for which this value is not known, the position value
- * should be {@link AudioSystem#NOT_SPECIFIED}.
+ * Note that this field is relevant only to certain events generated by data
+ * lines, such as {@code START} and {@code STOP}. For events generated by
+ * lines that do not count sample frames, and for any other events for which
+ * this value is not known, the position value should be
+ * {@link AudioSystem#NOT_SPECIFIED}.
*
* @return the line's position as a sample frame number
*/
/*
- * $$kk: 04.20.99: note to myself: should make sure our implementation is consistent with this.
+ * $$kk: 04.20.99: note to myself: should make sure our implementation is
+ * consistent with this.
* which is a reasonable definition....
*/
public final long getFramePosition() {
@@ -132,10 +139,12 @@
}
/**
- * Obtains a string representation of the event. The contents of the string may vary
- * between implementations of Java Sound.
- * @return a string describing the event.
+ * Obtains a string representation of the event. The contents of the string
+ * may vary between implementations of Java Sound.
+ *
+ * @return a string describing the event
*/
+ @Override
public String toString() {
String sType = "";
if (type != null) sType = type.toString()+" ";
@@ -148,16 +157,15 @@
return new String(sType + "event from line " + sLine);
}
-
/**
- * The LineEvent.Type inner class identifies what kind of event occurred on a line.
- * Static instances are provided for the common types (OPEN, CLOSE, START, and STOP).
+ * The LineEvent.Type inner class identifies what kind of event occurred on
+ * a line. Static instances are provided for the common types (OPEN, CLOSE,
+ * START, and STOP).
*
* @see LineEvent#getType()
*/
public static class Type {
-
/**
* Type name.
*/
@@ -166,82 +174,84 @@
/**
* Constructs a new event type.
- * @param name name of the type
+ *
+ * @param name name of the type
*/
protected Type(String name) {
this.name = name;
}
+ //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
- //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
/**
* Indicates whether the specified object is equal to this event type,
- * returning true if the objects are identical.
- * @param obj the reference object with which to compare
- * @return true if this event type is the same as
- * obj; false otherwise
+ * returning {@code true} if the objects are identical.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if this event type is the same as {@code obj};
+ * {@code false} otherwise
*/
+ @Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
-
/**
* Finalizes the hashcode method.
*/
+ @Override
public final int hashCode() {
return super.hashCode();
}
-
/**
* Returns the type name as the string representation.
*/
+ @Override
public String toString() {
return name;
}
-
// LINE EVENT TYPE DEFINES
/**
* A type of event that is sent when a line opens, reserving system
* resources for itself.
+ *
* @see #CLOSE
* @see Line#open
*/
public static final Type OPEN = new Type("Open");
-
/**
* A type of event that is sent when a line closes, freeing the system
* resources it had obtained when it was opened.
+ *
* @see #OPEN
* @see Line#close
*/
public static final Type CLOSE = new Type("Close");
-
/**
* A type of event that is sent when a line begins to engage in active
* input or output of audio data in response to a
* {@link DataLine#start start} request.
+ *
* @see #STOP
* @see DataLine#start
*/
public static final Type START = new Type("Start");
-
/**
- * A type of event that is sent when a line ceases active input or output
- * of audio data in response to a {@link DataLine#stop stop} request,
- * or because the end of media has been reached.
+ * A type of event that is sent when a line ceases active input or
+ * output of audio data in response to a {@link DataLine#stop stop}
+ * request, or because the end of media has been reached.
+ *
* @see #START
* @see DataLine#stop
*/
public static final Type STOP = new Type("Stop");
-
/**
* A type of event that is sent when a line ceases to engage in active
* input or output of audio data because the end of media has been reached.
@@ -255,7 +265,6 @@
*/
//public static final Type EOM = new Type("EOM");
-
/**
* A type of event that is sent when a line begins to engage in active
* input or output of audio data. Examples of when this happens are
@@ -268,7 +277,6 @@
*/
//public static final Type ACTIVE = new Type("ACTIVE");
-
/**
* A type of event that is sent when a line ceases active input or output
* of audio data.
@@ -276,7 +284,5 @@
* @see DataLine#stop
*/
//public static final Type INACTIVE = new Type("INACTIVE");
-
- } // class Type
-
-} // class LineEvent
+ }
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/LineListener.java
--- a/jdk/src/share/classes/javax/sound/sampled/LineListener.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/LineListener.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,44 +25,27 @@
package javax.sound.sampled;
-
+import java.util.EventListener;
/**
- * Instances of classes that implement the LineListener interface can register to
- * receive events when a line's status changes.
+ * Instances of classes that implement the {@code LineListener} interface can
+ * register to receive events when a line's status changes.
*
* @author Kara Kytle
- *
* @see Line
* @see Line#addLineListener
* @see Line#removeLineListener
* @see LineEvent
- *
* @since 1.3
*/
-/*
- * Instances of classes that implement the LineListener interface can register to
- * receive events when a line's status changes.
- *
- * @see Line
- * @see Line#addLineListener
- * @see Line#removeLineListener
- * @see LineEvent
- *
- * @author Kara Kytle
- */
-public interface LineListener extends java.util.EventListener {
+public interface LineListener extends EventListener {
/**
- * Informs the listener that a line's state has changed. The listener can then invoke
- * LineEvent methods to obtain information about the event.
- * @param event a line event that describes the change
+ * Informs the listener that a line's state has changed. The listener can
+ * then invoke {@code LineEvent} methods to obtain information about the
+ * event.
+ *
+ * @param event a line event that describes the change
*/
- /*
- * Informs the listener that a line's state has changed. The listener can then invoke
- * LineEvent methods to obtain information about the event.
- * @param event a line event that describes the change
- */
- public void update(LineEvent event);
-
-} // interface LineListener
+ void update(LineEvent event);
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/LineUnavailableException.java
--- a/jdk/src/share/classes/javax/sound/sampled/LineUnavailableException.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/LineUnavailableException.java Wed Jun 04 17:14:56 2014 +0400
@@ -26,43 +26,32 @@
package javax.sound.sampled;
/**
- * A LineUnavailableException is an exception indicating that a
- * line cannot be opened because it is unavailable. This situation
- * arises most commonly when a requested line is already in use
- * by another application.
+ * A {@code LineUnavailableException} is an exception indicating that a line
+ * cannot be opened because it is unavailable. This situation arises most
+ * commonly when a requested line is already in use by another application.
*
* @author Kara Kytle
* @since 1.3
*/
-/*
- * A LinenavailableException is an exception indicating that a
- * line annot be opened because it is unavailable. This situation
- * arises most commonly when a line is requested when it is already in use
- * by another application.
- *
- * @author Kara Kytle
- */
+public class LineUnavailableException extends Exception {
-public class LineUnavailableException extends Exception {
private static final long serialVersionUID = -2046718279487432130L;
/**
- * Constructs a LineUnavailableException that has
- * null as its error detail message.
+ * Constructs a {@code LineUnavailableException} that has {@code null} as
+ * its error detail message.
*/
public LineUnavailableException() {
-
super();
}
/**
- * Constructs a LineUnavailableException that has
- * the specified detail message.
+ * Constructs a {@code LineUnavailableException} that has the specified
+ * detail message.
*
- * @param message a string containing the error detail message
+ * @param message a string containing the error detail message
*/
- public LineUnavailableException(String message) {
-
+ public LineUnavailableException(final String message) {
super(message);
}
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/Mixer.java
--- a/jdk/src/share/classes/javax/sound/sampled/Mixer.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/Mixer.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,30 +25,27 @@
package javax.sound.sampled;
-
/**
- * A mixer is an audio device with one or more lines. It need not be
- * designed for mixing audio signals. A mixer that actually mixes audio
- * has multiple input (source) lines and at least one output (target) line.
- * The former are often instances of classes that implement
- * {@link SourceDataLine},
- * and the latter, {@link TargetDataLine}. {@link Port}
- * objects, too, are either source lines or target lines.
- * A mixer can accept prerecorded, loopable sound as input, by having
- * some of its source lines be instances of objects that implement the
- * {@link Clip} interface.
+ * A mixer is an audio device with one or more lines. It need not be designed
+ * for mixing audio signals. A mixer that actually mixes audio has multiple
+ * input (source) lines and at least one output (target) line. The former are
+ * often instances of classes that implement {@link SourceDataLine}, and the
+ * latter, {@link TargetDataLine}. {@link Port} objects, too, are either source
+ * lines or target lines. A mixer can accept prerecorded, loopable sound as
+ * input, by having some of its source lines be instances of objects that
+ * implement the {@link Clip} interface.
*
- * Through methods of the Line interface, which Mixer extends,
- * a mixer might provide a set of controls that are global to the mixer. For example,
- * the mixer can have a master gain control. These global controls are distinct
- * from the controls belonging to each of the mixer's individual lines.
+ * Through methods of the {@code Line} interface, which {@code Mixer} extends, a
+ * mixer might provide a set of controls that are global to the mixer. For
+ * example, the mixer can have a master gain control. These global controls are
+ * distinct from the controls belonging to each of the mixer's individual lines.
*
- * Some mixers, especially
- * those with internal digital mixing capabilities, may provide
- * additional capabilities by implementing the DataLine interface.
+ * Some mixers, especially those with internal digital mixing capabilities, may
+ * provide additional capabilities by implementing the {@code DataLine}
+ * interface.
*
- * A mixer can support synchronization of its lines. When one line in
- * a synchronized group is started or stopped, the other lines in the group
+ * A mixer can support synchronization of its lines. When one line in a
+ * synchronized group is started or stopped, the other lines in the group
* automatically start or stop simultaneously with the explicitly affected one.
*
* @author Kara Kytle
@@ -59,198 +56,201 @@
/**
* Obtains information about this mixer, including the product's name,
* version, vendor, etc.
+ *
* @return a mixer info object that describes this mixer
* @see Mixer.Info
*/
- public Info getMixerInfo();
-
+ Info getMixerInfo();
/**
- * Obtains information about the set of source lines supported
- * by this mixer.
- * Some source lines may only be available when this mixer is open.
- * @return array of Line.Info objects representing source lines
- * for this mixer. If no source lines are supported,
- * an array of length 0 is returned.
+ * Obtains information about the set of source lines supported by this
+ * mixer. Some source lines may only be available when this mixer is open.
+ *
+ * @return array of {@code Line.Info} objects representing source lines for
+ * this mixer. If no source lines are supported, an array of length
+ * 0 is returned.
*/
- public Line.Info[] getSourceLineInfo();
+ Line.Info[] getSourceLineInfo();
/**
- * Obtains information about the set of target lines supported
- * by this mixer.
- * Some target lines may only be available when this mixer is open.
- * @return array of Line.Info objects representing target lines
- * for this mixer. If no target lines are supported,
- * an array of length 0 is returned.
+ * Obtains information about the set of target lines supported by this
+ * mixer. Some target lines may only be available when this mixer is open.
+ *
+ * @return array of {@code Line.Info} objects representing target lines for
+ * this mixer. If no target lines are supported, an array of length
+ * 0 is returned.
*/
- public Line.Info[] getTargetLineInfo();
-
+ Line.Info[] getTargetLineInfo();
/**
- * Obtains information about source lines of a particular type supported
- * by the mixer.
- * Some source lines may only be available when this mixer is open.
- * @param info a Line.Info object describing lines about which information
- * is queried
- * @return an array of Line.Info objects describing source lines matching
- * the type requested. If no matching source lines are supported, an array of length 0
- * is returned.
+ * Obtains information about source lines of a particular type supported by
+ * the mixer. Some source lines may only be available when this mixer is
+ * open.
+ *
+ * @param info a {@code Line.Info} object describing lines about which
+ * information is queried
+ * @return an array of {@code Line.Info} objects describing source lines
+ * matching the type requested. If no matching source lines are
+ * supported, an array of length 0 is returned.
*/
- public Line.Info[] getSourceLineInfo(Line.Info info);
-
+ Line.Info[] getSourceLineInfo(Line.Info info);
/**
- * Obtains information about target lines of a particular type supported
- * by the mixer.
- * Some target lines may only be available when this mixer is open.
- * @param info a Line.Info object describing lines about which information
- * is queried
- * @return an array of Line.Info objects describing target lines matching
- * the type requested. If no matching target lines are supported, an array of length 0
- * is returned.
+ * Obtains information about target lines of a particular type supported by
+ * the mixer. Some target lines may only be available when this mixer is
+ * open.
+ *
+ * @param info a {@code Line.Info} object describing lines about which
+ * information is queried
+ * @return an array of {@code Line.Info} objects describing target lines
+ * matching the type requested. If no matching target lines are
+ * supported, an array of length 0 is returned.
*/
- public Line.Info[] getTargetLineInfo(Line.Info info);
-
+ Line.Info[] getTargetLineInfo(Line.Info info);
/**
- * Indicates whether the mixer supports a line (or lines) that match
- * the specified Line.Info object.
- * Some lines may only be supported when this mixer is open.
- * @param info describes the line for which support is queried
- * @return true if at least one matching line is
- * supported, false otherwise
+ * Indicates whether the mixer supports a line (or lines) that match the
+ * specified {@code Line.Info} object. Some lines may only be supported when
+ * this mixer is open.
+ *
+ * @param info describes the line for which support is queried
+ * @return {@code true} if at least one matching line is supported,
+ * {@code false} otherwise
*/
- public boolean isLineSupported(Line.Info info);
+ boolean isLineSupported(Line.Info info);
/**
* Obtains a line that is available for use and that matches the description
- * in the specified Line.Info object.
+ * in the specified {@code Line.Info} object.
+ *
+ * If a {@code DataLine} is requested, and {@code info} is an instance of + * {@code DataLine.Info} specifying at least one fully qualified audio + * format, the last one will be used as the default format of the returned + * {@code DataLine}. * - *
If a DataLine is requested, and info
- * is an instance of DataLine.Info specifying at
- * least one fully qualified audio format, the last one
- * will be used as the default format of the returned
- * DataLine.
- *
- * @param info describes the desired line
+ * @param info describes the desired line
* @return a line that is available for use and that matches the description
- * in the specified {@code Line.Info} object
- * @throws LineUnavailableException if a matching line
- * is not available due to resource restrictions
- * @throws IllegalArgumentException if this mixer does
- * not support any lines matching the description
- * @throws SecurityException if a matching line
- * is not available due to security restrictions
+ * in the specified {@code Line.Info} object
+ * @throws LineUnavailableException if a matching line is not available due
+ * to resource restrictions
+ * @throws IllegalArgumentException if this mixer does not support any lines
+ * matching the description
+ * @throws SecurityException if a matching line is not available due to
+ * security restrictions
*/
- public Line getLine(Line.Info info) throws LineUnavailableException;
+ Line getLine(Line.Info info) throws LineUnavailableException;
//$$fb 2002-04-12: fix for 4667258: behavior of Mixer.getMaxLines(Line.Info) method doesn't match the spec
/**
- * Obtains the approximate maximum number of lines of the requested type that can be open
- * simultaneously on the mixer.
+ * Obtains the approximate maximum number of lines of the requested type
+ * that can be open simultaneously on the mixer.
*
- * Certain types of mixers do not have a hard bound and may allow opening more lines.
- * Since certain lines are a shared resource, a mixer may not be able to open the maximum
- * number of lines if another process has opened lines of this mixer.
+ * Certain types of mixers do not have a hard bound and may allow opening
+ * more lines. Since certain lines are a shared resource, a mixer may not be
+ * able to open the maximum number of lines if another process has opened
+ * lines of this mixer.
*
- * The requested type is any line that matches the description in
- * the provided Line.Info object. For example, if the info
- * object represents a speaker
- * port, and the mixer supports exactly one speaker port, this method
- * should return 1. If the info object represents a source data line
- * and the mixer supports the use of 32 source data lines simultaneously,
- * the return value should be 32.
- * If there is no limit, this function returns AudioSystem.NOT_SPECIFIED.
- * @param info a Line.Info that describes the line for which
- * the number of supported instances is queried
- * @return the maximum number of matching lines supported, or AudioSystem.NOT_SPECIFIED
+ * The requested type is any line that matches the description in the
+ * provided {@code Line.Info} object. For example, if the info object
+ * represents a speaker port, and the mixer supports exactly one speaker
+ * port, this method should return 1. If the info object represents a
+ * source data line and the mixer supports the use of 32 source data lines
+ * simultaneously, the return value should be 32. If there is no limit, this
+ * function returns {@code AudioSystem.NOT_SPECIFIED}.
+ *
+ * @param info a {@code Line.Info} that describes the line for which the
+ * number of supported instances is queried
+ * @return the maximum number of matching lines supported, or
+ * {@code AudioSystem.NOT_SPECIFIED}
*/
- public int getMaxLines(Line.Info info);
-
+ int getMaxLines(Line.Info info);
/**
* Obtains the set of all source lines currently open to this mixer.
*
- * @return the source lines currently open to the mixer.
- * If no source lines are currently open to this mixer, an
- * array of length 0 is returned.
- * @throws SecurityException if the matching lines
- * are not available due to security restrictions
+ * @return the source lines currently open to the mixer. If no source lines
+ * are currently open to this mixer, an array of length 0 is
+ * returned.
+ * @throws SecurityException if the matching lines are not available due to
+ * security restrictions
*/
- public Line[] getSourceLines();
+ Line[] getSourceLines();
/**
* Obtains the set of all target lines currently open from this mixer.
*
- * @return target lines currently open from the mixer.
- * If no target lines are currently open from this mixer, an
- * array of length 0 is returned.
- * @throws SecurityException if the matching lines
- * are not available due to security restrictions
+ * @return target lines currently open from the mixer. If no target lines
+ * are currently open from this mixer, an array of length 0 is
+ * returned.
+ * @throws SecurityException if the matching lines are not available due to
+ * security restrictions
*/
- public Line[] getTargetLines();
+ Line[] getTargetLines();
/**
- * Synchronizes two or more lines. Any subsequent command that starts or stops
- * audio playback or capture for one of these lines will exert the
- * same effect on the other lines in the group, so that they start or stop playing or
- * capturing data simultaneously.
+ * Synchronizes two or more lines. Any subsequent command that starts or
+ * stops audio playback or capture for one of these lines will exert the
+ * same effect on the other lines in the group, so that they start or stop
+ * playing or capturing data simultaneously.
*
- * @param lines the lines that should be synchronized
- * @param maintainSync true if the synchronization
- * must be precisely maintained (i.e., the synchronization must be sample-accurate)
- * at all times during operation of the lines , or false
- * if precise synchronization is required only during start and stop operations
- *
+ * @param lines the lines that should be synchronized
+ * @param maintainSync {@code true} if the synchronization must be
+ * precisely maintained (i.e., the synchronization must be
+ * sample-accurate) at all times during operation of the lines, or
+ * {@code false} if precise synchronization is required only during
+ * start and stop operations
* @throws IllegalArgumentException if the lines cannot be synchronized.
- * This may occur if the lines are of different types or have different
- * formats for which this mixer does not support synchronization, or if
- * all lines specified do not belong to this mixer.
+ * This may occur if the lines are of different types or have
+ * different formats for which this mixer does not support
+ * synchronization, or if all lines specified do not belong to this
+ * mixer.
*/
- public void synchronize(Line[] lines, boolean maintainSync);
+ void synchronize(Line[] lines, boolean maintainSync);
/**
- * Releases synchronization for the specified lines. The array must
- * be identical to one for which synchronization has already been
- * established; otherwise an exception may be thrown. However, null
- * may be specified, in which case all currently synchronized lines that belong
- * to this mixer are unsynchronized.
- * @param lines the synchronized lines for which synchronization should be
- * released, or null for all this mixer's synchronized lines
+ * Releases synchronization for the specified lines. The array must be
+ * identical to one for which synchronization has already been established;
+ * otherwise an exception may be thrown. However, {@code null} may be
+ * specified, in which case all currently synchronized lines that belong to
+ * this mixer are unsynchronized.
*
+ * @param lines the synchronized lines for which synchronization should be
+ * released, or {@code null} for all this mixer's synchronized
+ * lines
* @throws IllegalArgumentException if the lines cannot be unsynchronized.
- * This may occur if the argument specified does not exactly match a set
- * of lines for which synchronization has already been established.
+ * This may occur if the argument specified does not exactly match
+ * a set of lines for which synchronization has already been
+ * established.
*/
- public void unsynchronize(Line[] lines);
-
+ void unsynchronize(Line[] lines);
/**
- * Reports whether this mixer supports synchronization of the specified set of lines.
+ * Reports whether this mixer supports synchronization of the specified set
+ * of lines.
*
- * @param lines the set of lines for which synchronization support is queried
- * @param maintainSync true if the synchronization
- * must be precisely maintained (i.e., the synchronization must be sample-accurate)
- * at all times during operation of the lines , or false
- * if precise synchronization is required only during start and stop operations
- *
- * @return true if the lines can be synchronized, false
- * otherwise
+ * @param lines the set of lines for which synchronization support is
+ * queried
+ * @param maintainSync {@code true} if the synchronization must be
+ * precisely maintained (i.e., the synchronization must be
+ * sample-accurate) at all times during operation of the lines, or
+ * {@code false} if precise synchronization is required only during
+ * start and stop operations
+ * @return {@code true} if the lines can be synchronized, {@code false}
+ * otherwise
*/
- public boolean isSynchronizationSupported(Line[] lines, boolean maintainSync);
-
+ boolean isSynchronizationSupported(Line[] lines, boolean maintainSync);
/**
- * The Mixer.Info class represents information about an audio mixer,
+ * The {@code Mixer.Info} class represents information about an audio mixer,
* including the product's name, version, and vendor, along with a textual
- * description. This information may be retrieved through the
- * {@link Mixer#getMixerInfo() getMixerInfo}
- * method of the Mixer interface.
+ * description. This information may be retrieved through the
+ * {@link Mixer#getMixerInfo() getMixerInfo} method of the {@code Mixer}
+ * interface.
*
* @author Kara Kytle
* @since 1.3
*/
- public static class Info {
+ class Info {
/**
* Mixer name.
@@ -273,13 +273,14 @@
private final String version;
/**
- * Constructs a mixer's info object, passing it the given
- * textual information.
- * @param name the name of the mixer
- * @param vendor the company who manufactures or creates the hardware
- * or software mixer
- * @param description descriptive text about the mixer
- * @param version version information for the mixer
+ * Constructs a mixer's info object, passing it the given textual
+ * information.
+ *
+ * @param name the name of the mixer
+ * @param vendor the company who manufactures or creates the
+ * hardware or software mixer
+ * @param description descriptive text about the mixer
+ * @param version version information for the mixer
*/
protected Info(String name, String vendor, String description, String version) {
@@ -289,15 +290,16 @@
this.version = version;
}
-
/**
- * Indicates whether two info objects are equal, returning true if
- * they are identical.
- * @param obj the reference object with which to compare this info
- * object
- * @return true if this info object is the same as the
- * obj argument; false otherwise
+ * Indicates whether two info objects are equal, returning {@code true}
+ * if they are identical.
+ *
+ * @param obj the reference object with which to compare this info
+ * object
+ * @return {@code true} if this info object is the same as the
+ * {@code obj} argument; {@code false} otherwise
*/
+ @Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
@@ -307,12 +309,14 @@
*
* @return the hashcode for this object
*/
+ @Override
public final int hashCode() {
return super.hashCode();
}
/**
* Obtains the name of the mixer.
+ *
* @return a string that names the mixer
*/
public final String getName() {
@@ -321,6 +325,7 @@
/**
* Obtains the vendor of the mixer.
+ *
* @return a string that names the mixer's vendor
*/
public final String getVendor() {
@@ -329,6 +334,7 @@
/**
* Obtains the description of the mixer.
+ *
* @return a textual description of the mixer
*/
public final String getDescription() {
@@ -337,6 +343,7 @@
/**
* Obtains the version of the mixer.
+ *
* @return textual version information for the mixer
*/
public final String getVersion() {
@@ -345,10 +352,12 @@
/**
* Provides a string representation of the mixer info.
+ *
* @return a string describing the info object
*/
+ @Override
public final String toString() {
return (name + ", version " + version);
}
- } // class Info
+ }
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/Port.java
--- a/jdk/src/share/classes/javax/sound/sampled/Port.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/Port.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,41 +25,36 @@
package javax.sound.sampled;
-
/**
* Ports are simple lines for input or output of audio to or from audio devices.
- * Common examples of ports that act as source lines (mixer inputs) include the microphone,
- * line input, and CD-ROM drive. Ports that act as target lines (mixer outputs) include the
- * speaker, headphone, and line output. You can access port using a {@link Port.Info}
- * object.
+ * Common examples of ports that act as source lines (mixer inputs) include the
+ * microphone, line input, and CD-ROM drive. Ports that act as target lines
+ * (mixer outputs) include the speaker, headphone, and line output. You can
+ * access port using a {@link Port.Info} object.
*
* @author Kara Kytle
* @since 1.3
*/
public interface Port extends Line {
-
- // INNER CLASSES
-
-
/**
- * The Port.Info class extends {@link Line.Info}
- * with additional information specific to ports, including the port's name
- * and whether it is a source or a target for its mixer.
- * By definition, a port acts as either a source or a target to its mixer,
- * but not both. (Audio input ports are sources; audio output ports are targets.)
+ * The {@code Port.Info} class extends {@code Line.Info} with additional
+ * information specific to ports, including the port's name and whether it
+ * is a source or a target for its mixer. By definition, a port acts as
+ * either a source or a target to its mixer, but not both. (Audio input
+ * ports are sources; audio output ports are targets.)
*
- * To learn what ports are available, you can retrieve port info objects through the
- * {@link Mixer#getSourceLineInfo getSourceLineInfo} and
- * {@link Mixer#getTargetLineInfo getTargetLineInfo}
- * methods of the Mixer interface. Instances of the
- * Port.Info class may also be constructed and used to obtain
- * lines matching the parameters specified in the Port.Info object.
+ * To learn what ports are available, you can retrieve port info objects
+ * through the {@link Mixer#getSourceLineInfo getSourceLineInfo} and
+ * {@link Mixer#getTargetLineInfo getTargetLineInfo} methods of the
+ * {@code Mixer} interface. Instances of the {@code Port.Info} class may
+ * also be constructed and used to obtain lines matching the parameters
+ * specified in the {@code Port.Info} object.
*
* @author Kara Kytle
* @since 1.3
*/
- public static class Info extends Line.Info {
+ class Info extends Line.Info {
// AUDIO PORT TYPE DEFINES
@@ -68,7 +63,8 @@
// SOURCE PORTS
/**
- * A type of port that gets audio from a built-in microphone or a microphone jack.
+ * A type of port that gets audio from a built-in microphone or a
+ * microphone jack.
*/
public static final Info MICROPHONE = new Info(Port.class,"MICROPHONE", true);
@@ -86,7 +82,8 @@
// TARGET PORTS
/**
- * A type of port that sends audio to a built-in speaker or a speaker jack.
+ * A type of port that sends audio to a built-in speaker or a speaker
+ * jack.
*/
public static final Info SPEAKER = new Info(Port.class,"SPEAKER", false);
@@ -113,19 +110,16 @@
private String name;
private boolean isSource;
-
- // CONSTRUCTOR
-
/**
- * Constructs a port's info object from the information given.
- * This constructor is typically used by an implementation
- * of Java Sound to describe a supported line.
+ * Constructs a port's info object from the information given. This
+ * constructor is typically used by an implementation of Java Sound to
+ * describe a supported line.
*
- * @param lineClass the class of the port described by the info object.
- * @param name the string that names the port
- * @param isSource true if the port is a source port (such
- * as a microphone), false if the port is a target port
- * (such as a speaker).
+ * @param lineClass the class of the port described by the info object
+ * @param name the string that names the port
+ * @param isSource {@code true} if the port is a source port (such as a
+ * microphone), {@code false} if the port is a target port
+ * (such as a speaker)
*/
public Info(Class lineClass, String name, boolean isSource) {
@@ -134,11 +128,9 @@
this.isSource = isSource;
}
-
- // METHODS
-
/**
* Obtains the name of the port.
+ *
* @return the string that names the port
*/
public String getName() {
@@ -147,20 +139,23 @@
/**
* Indicates whether the port is a source or a target for its mixer.
- * @return true if the port is a source port (such
- * as a microphone), false if the port is a target port
- * (such as a speaker).
+ *
+ * @return {@code true} if the port is a source port (such as a
+ * microphone), {@code false} if the port is a target port
+ * (such as a speaker)
*/
public boolean isSource() {
return isSource;
}
/**
- * Indicates whether this info object specified matches this one.
- * To match, the match requirements of the superclass must be
- * met and the types must be equal.
- * @param info the info object for which the match is queried
+ * Indicates whether this info object specified matches this one. To
+ * match, the match requirements of the superclass must be met and the
+ * types must be equal.
+ *
+ * @param info the info object for which the match is queried
*/
+ @Override
public boolean matches(Line.Info info) {
if (! (super.matches(info)) ) {
@@ -178,31 +173,30 @@
return true;
}
-
/**
- * Finalizes the equals method
+ * Finalizes the equals method.
*/
+ @Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
/**
- * Finalizes the hashCode method
+ * Finalizes the hashCode method.
*/
+ @Override
public final int hashCode() {
return super.hashCode();
}
-
-
/**
- * Provides a String representation
- * of the port.
- * @return a string that describes the port
+ * Provides a {@code String} representation of the port.
+ *
+ * @return a string that describes the port
*/
+ @Override
public final String toString() {
return (name + ((isSource == true) ? " source" : " target") + " port");
}
-
- } // class Info
+ }
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/ReverbType.java
--- a/jdk/src/share/classes/javax/sound/sampled/ReverbType.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/ReverbType.java Wed Jun 04 17:14:56 2014 +0400
@@ -25,46 +25,41 @@
package javax.sound.sampled;
-
/**
- * The ReverbType class provides methods for
- * accessing various reverberation settings to be applied to
- * an audio signal.
+ * The {@code ReverbType} class provides methods for accessing various
+ * reverberation settings to be applied to an audio signal.
*
- * Reverberation simulates the reflection of sound off of - * the walls, ceiling, and floor of a room. Depending on - * the size of the room, and how absorbent or reflective the materials in the - * room's surfaces are, the sound might bounce around for a - * long time before dying away. + * Reverberation simulates the reflection of sound off of the walls, ceiling, + * and floor of a room. Depending on the size of the room, and how absorbent or + * reflective the materials in the room's surfaces are, the sound might bounce + * around for a long time before dying away. *
- * The reverberation parameters provided by ReverbType consist
- * of the delay time and intensity of early reflections, the delay time and
- * intensity of late reflections, and an overall decay time.
- * Early reflections are the initial individual low-order reflections of the
- * direct signal off the surfaces in the room.
- * The late Reflections are the dense, high-order reflections that characterize
- * the room's reverberation.
- * The delay times for the start of these two reflection types give the listener
- * a sense of the overall size and complexity of the room's shape and contents.
- * The larger the room, the longer the reflection delay times.
- * The early and late reflections' intensities define the gain (in decibels) of the reflected
- * signals as compared to the direct signal. These intensities give the
- * listener an impression of the absorptive nature of the surfaces and objects
- * in the room.
+ * The reverberation parameters provided by {@code ReverbType} consist of the
+ * delay time and intensity of early reflections, the delay time and intensity
+ * of late reflections, and an overall decay time. Early reflections are the
+ * initial individual low-order reflections of the direct signal off the
+ * surfaces in the room. The late Reflections are the dense, high-order
+ * reflections that characterize the room's reverberation. The delay times for
+ * the start of these two reflection types give the listener a sense of the
+ * overall size and complexity of the room's shape and contents. The larger the
+ * room, the longer the reflection delay times. The early and late reflections'
+ * intensities define the gain (in decibels) of the reflected signals as
+ * compared to the direct signal. These intensities give the listener an
+ * impression of the absorptive nature of the surfaces and objects in the room.
* The decay time defines how long the reverberation takes to exponentially
- * decay until it is no longer perceptible ("effective zero").
- * The larger and less absorbent the surfaces, the longer the decay time.
+ * decay until it is no longer perceptible ("effective zero"). The larger and
+ * less absorbent the surfaces, the longer the decay time.
*
- * The set of parameters defined here may not include all aspects of reverberation - * as specified by some systems. For example, the Midi Manufacturer's Association - * (MMA) has an Interactive Audio Special Interest Group (IASIG), which has a - * 3-D Working Group that has defined a Level 2 Spec (I3DL2). I3DL2 - * supports filtering of reverberation and - * control of reverb density. These properties are not included in the JavaSound 1.0 - * definition of a reverb control. In such a case, the implementing system - * should either extend the defined reverb control to include additional - * parameters, or else interpret the system's additional capabilities in a way that fits - * the model described here. + * The set of parameters defined here may not include all aspects of + * reverberation as specified by some systems. For example, the Midi + * Manufacturer's Association (MMA) has an Interactive Audio Special Interest + * Group (IASIG), which has a 3-D Working Group that has defined a Level 2 Spec + * (I3DL2). I3DL2 supports filtering of reverberation and control of reverb + * density. These properties are not included in the JavaSound 1.0 definition of + * a reverb control. In such a case, the implementing system should either + * extend the defined reverb control to include additional parameters, or else + * interpret the system's additional capabilities in a way that fits the model + * described here. *
* If implementing JavaSound on a I3DL2-compliant device: *
- * The following table shows what parameter values an implementation might use for a - * representative set of reverberation settings. + * The following table shows what parameter values an implementation might use + * for a representative set of reverberation settings. *
*
* Reverberation Types and Parameters
@@ -142,7 +137,7 @@
public class ReverbType {
/**
- * Descriptive name of the reverb type..
+ * Descriptive name of the reverb type.
*/
private String name;
@@ -167,20 +162,25 @@
private float lateReflectionIntensity;
/**
- * Total decay time
+ * Total decay time.
*/
private int decayTime;
-
/**
* Constructs a new reverb type that has the specified reverberation
* parameter values.
- * @param name the name of the new reverb type, or a zero-length String
- * @param earlyReflectionDelay the new type's early reflection delay time in microseconds
- * @param earlyReflectionIntensity the new type's early reflection intensity in dB
- * @param lateReflectionDelay the new type's late reflection delay time in microseconds
- * @param lateReflectionIntensity the new type's late reflection intensity in dB
- * @param decayTime the new type's decay time in microseconds
+ *
+ * @param name the name of the new reverb type, or a zero-length
+ * {@code String}
+ * @param earlyReflectionDelay the new type's early reflection delay time
+ * in microseconds
+ * @param earlyReflectionIntensity the new type's early reflection
+ * intensity in dB
+ * @param lateReflectionDelay the new type's late reflection delay time in
+ * microseconds
+ * @param lateReflectionIntensity the new type's late reflection intensity
+ * in dB
+ * @param decayTime the new type's decay time in microseconds
*/
protected ReverbType(String name, int earlyReflectionDelay, float earlyReflectionIntensity, int lateReflectionDelay, float lateReflectionIntensity, int decayTime) {
@@ -192,9 +192,9 @@
this.decayTime = decayTime;
}
-
/**
* Obtains the name of this reverb type.
+ *
* @return the name of this reverb type
* @since 1.5
*/
@@ -202,89 +202,88 @@
return name;
}
-
/**
- * Returns the early reflection delay time in microseconds.
- * This is the amount of time between when the direct signal is
- * heard and when the first early reflections are heard.
- * @return early reflection delay time for this reverb type, in microseconds
+ * Returns the early reflection delay time in microseconds. This is the
+ * amount of time between when the direct signal is heard and when the first
+ * early reflections are heard.
+ *
+ * @return early reflection delay time for this reverb type, in microseconds
*/
public final int getEarlyReflectionDelay() {
return earlyReflectionDelay;
}
-
/**
- * Returns the early reflection intensity in decibels.
- * This is the amplitude attenuation of the first early reflections
- * relative to the direct signal.
- * @return early reflection intensity for this reverb type, in dB
+ * Returns the early reflection intensity in decibels. This is the amplitude
+ * attenuation of the first early reflections relative to the direct signal.
+ *
+ * @return early reflection intensity for this reverb type, in dB
*/
public final float getEarlyReflectionIntensity() {
return earlyReflectionIntensity;
}
-
/**
- * Returns the late reflection delay time in microseconds.
- * This is the amount of time between when the first early reflections
- * are heard and when the first late reflections are heard.
- * @return late reflection delay time for this reverb type, in microseconds
+ * Returns the late reflection delay time in microseconds. This is the
+ * amount of time between when the first early reflections are heard and
+ * when the first late reflections are heard.
+ *
+ * @return late reflection delay time for this reverb type, in microseconds
*/
public final int getLateReflectionDelay() {
return lateReflectionDelay;
}
-
/**
- * Returns the late reflection intensity in decibels.
- * This is the amplitude attenuation of the first late reflections
- * relative to the direct signal.
- * @return late reflection intensity for this reverb type, in dB
+ * Returns the late reflection intensity in decibels. This is the amplitude
+ * attenuation of the first late reflections relative to the direct signal.
+ *
+ * @return late reflection intensity for this reverb type, in dB
*/
public final float getLateReflectionIntensity() {
return lateReflectionIntensity;
}
-
/**
- * Obtains the decay time, which is the amount of time over which the
- * late reflections attenuate to effective zero. The effective zero
- * value is implementation-dependent.
- * @return the decay time of the late reflections, in microseconds
+ * Obtains the decay time, which is the amount of time over which the late
+ * reflections attenuate to effective zero. The effective zero value is
+ * implementation-dependent.
+ *
+ * @return the decay time of the late reflections, in microseconds
*/
public final int getDecayTime() {
return decayTime;
}
-
/**
* Indicates whether the specified object is equal to this reverb type,
- * returning true if the objects are identical.
- * @param obj the reference object with which to compare
- * @return true if this reverb type is the same as
- * obj; false otherwise
+ * returning {@code true} if the objects are identical.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if this reverb type is the same as {@code obj};
+ * {@code false} otherwise
*/
+ @Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
-
/**
* Finalizes the hashcode method.
*/
+ @Override
public final int hashCode() {
return super.hashCode();
}
-
/**
- * Provides a String representation of the reverb type,
- * including its name and its parameter settings.
- * The exact contents of the string may vary between implementations of
- * Java Sound.
+ * Provides a {@code String} representation of the reverb type, including
+ * its name and its parameter settings. The exact contents of the string may
+ * vary between implementations of Java Sound.
+ *
* @return reverberation type name and description
*/
+ @Override
public final String toString() {
//$$fb2001-07-20: fix for bug 4385060: The "name" attribute of class "ReverbType" is not accessible.
@@ -295,5 +294,4 @@
" ns, late reflection intensity " + lateReflectionIntensity +
" dB, decay time " + decayTime);
}
-
-} // class ReverbType
+}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/SourceDataLine.java
--- a/jdk/src/share/classes/javax/sound/sampled/SourceDataLine.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/SourceDataLine.java Wed Jun 04 17:14:56 2014 +0400
@@ -25,36 +25,35 @@
package javax.sound.sampled;
-
/**
- * A source data line is a data line to which data may be written. It acts as
- * a source to its mixer. An application writes audio bytes to a source data line,
- * which handles the buffering of the bytes and delivers them to the mixer.
- * The mixer may mix the samples with those from other sources and then deliver
- * the mix to a target such as an output port (which may represent an audio output
+ * A source data line is a data line to which data may be written. It acts as a
+ * source to its mixer. An application writes audio bytes to a source data line,
+ * which handles the buffering of the bytes and delivers them to the mixer. The
+ * mixer may mix the samples with those from other sources and then deliver the
+ * mix to a target such as an output port (which may represent an audio output
* device on a sound card).
*
* Note that the naming convention for this interface reflects the relationship - * between the line and its mixer. From the perspective of an application, - * a source data line may act as a target for audio data. + * between the line and its mixer. From the perspective of an application, a + * source data line may act as a target for audio data. *
* A source data line can be obtained from a mixer by invoking the
- * {@link Mixer#getLine getLine} method of Mixer with
- * an appropriate {@link DataLine.Info} object.
+ * {@link Mixer#getLine getLine} method of {@code Mixer} with an appropriate
+ * {@link DataLine.Info} object.
*
- * The SourceDataLine interface provides a method for writing
- * audio data to the data line's buffer. Applications that play or mix
- * audio should write data to the source data line quickly enough to keep the
- * buffer from underflowing (emptying), which could cause discontinuities in
- * the audio that are perceived as clicks. Applications can use the
- * {@link DataLine#available available} method defined in the
- * DataLine interface to determine the amount of data currently
- * queued in the data line's buffer. The amount of data which can be written
- * to the buffer without blocking is the difference between the buffer size
- * and the amount of queued data. If the delivery of audio output
- * stops due to underflow, a {@link LineEvent.Type#STOP STOP} event is
- * generated. A {@link LineEvent.Type#START START} event is generated
- * when the audio output resumes.
+ * The {@code SourceDataLine} interface provides a method for writing audio data
+ * to the data line's buffer. Applications that play or mix audio should write
+ * data to the source data line quickly enough to keep the buffer from
+ * underflowing (emptying), which could cause discontinuities in the audio that
+ * are perceived as clicks. Applications can use the
+ * {@link DataLine#available available} method defined in the {@code DataLine}
+ * interface to determine the amount of data currently queued in the data line's
+ * buffer. The amount of data which can be written to the buffer without
+ * blocking is the difference between the buffer size and the amount of queued
+ * data. If the delivery of audio output stops due to underflow, a
+ * {@link LineEvent.Type#STOP STOP} event is generated. A
+ * {@link LineEvent.Type#START START} event is generated when the audio output
+ * resumes.
*
* @author Kara Kytle
* @see Mixer
@@ -64,138 +63,130 @@
*/
public interface SourceDataLine extends DataLine {
-
/**
* Opens the line with the specified format and suggested buffer size,
- * causing the line to acquire any required
- * system resources and become operational.
+ * causing the line to acquire any required system resources and become
+ * operational.
*
* The buffer size is specified in bytes, but must represent an integral
- * number of sample frames. Invoking this method with a requested buffer
+ * number of sample frames. Invoking this method with a requested buffer
* size that does not meet this requirement may result in an
- * IllegalArgumentException. The actual buffer size for the open line may
- * differ from the requested buffer size. The value actually set may be
- * queried by subsequently calling {@link DataLine#getBufferSize}.
+ * {@code IllegalArgumentException}. The actual buffer size for the open
+ * line may differ from the requested buffer size. The value actually set
+ * may be queried by subsequently calling {@link DataLine#getBufferSize}.
*
* If this operation succeeds, the line is marked as open, and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
- * line's listeners.
+ * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+ * listeners.
*
- * Invoking this method on a line which is already open is illegal
- * and may result in an IllegalStateException.
+ * Invoking this method on a line which is already open is illegal and may
+ * result in an {@code IllegalStateException}.
*
- * Note that some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * LineUnavailableException.
+ * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+ * such a line will always result in a {@code LineUnavailableException}.
*
- * @param format the desired audio format
- * @param bufferSize the desired buffer size
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IllegalArgumentException if the buffer size does not represent
- * an integral number of sample frames,
- * or if format is not fully specified or invalid
+ * @param format the desired audio format
+ * @param bufferSize the desired buffer size
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IllegalArgumentException if the buffer size does not represent an
+ * integral number of sample frames, or if {@code format} is not
+ * fully specified or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #open(AudioFormat)
* @see Line#open
* @see Line#close
* @see Line#isOpen
* @see LineEvent
*/
- public void open(AudioFormat format, int bufferSize) throws LineUnavailableException;
-
+ void open(AudioFormat format, int bufferSize)
+ throws LineUnavailableException;
/**
* Opens the line with the specified format, causing the line to acquire any
* required system resources and become operational.
- *
*
* The implementation chooses a buffer size, which is measured in bytes but
- * which encompasses an integral number of sample frames. The buffer size
+ * which encompasses an integral number of sample frames. The buffer size
* that the system has chosen may be queried by subsequently calling
- * {@link DataLine#getBufferSize}.
+ * {@link DataLine#getBufferSize}.
*
* If this operation succeeds, the line is marked as open, and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
- * line's listeners.
+ * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+ * listeners.
*
- * Invoking this method on a line which is already open is illegal
- * and may result in an IllegalStateException.
+ * Invoking this method on a line which is already open is illegal and may
+ * result in an {@code IllegalStateException}.
*
- * Note that some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * LineUnavailableException.
+ * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+ * such a line will always result in a {@code LineUnavailableException}.
*
- * @param format the desired audio format
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IllegalArgumentException if format
- * is not fully specified or invalid
+ * @param format the desired audio format
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IllegalArgumentException if {@code format} is not fully specified
+ * or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #open(AudioFormat, int)
* @see Line#open
* @see Line#close
* @see Line#isOpen
* @see LineEvent
*/
- public void open(AudioFormat format) throws LineUnavailableException;
-
+ void open(AudioFormat format) throws LineUnavailableException;
/**
- * Writes audio data to the mixer via this source data line. The requested
- * number of bytes of data are read from the specified array,
- * starting at the given offset into the array, and written to the data
- * line's buffer. If the caller attempts to write more data than can
- * currently be written (see {@link DataLine#available available}),
- * this method blocks until the requested amount of data has been written.
- * This applies even if the requested amount of data to write is greater
- * than the data line's buffer size. However, if the data line is closed,
- * stopped, or flushed before the requested amount has been written,
- * the method no longer blocks, but returns the number of bytes
- * written thus far.
+ * Writes audio data to the mixer via this source data line. The requested
+ * number of bytes of data are read from the specified array, starting at
+ * the given offset into the array, and written to the data line's buffer.
+ * If the caller attempts to write more data than can currently be written
+ * (see {@link DataLine#available available}), this method blocks until the
+ * requested amount of data has been written. This applies even if the
+ * requested amount of data to write is greater than the data line's buffer
+ * size. However, if the data line is closed, stopped, or flushed before the
+ * requested amount has been written, the method no longer blocks, but
+ * returns the number of bytes written thus far.
*
- * The number of bytes that can be written without blocking can be ascertained
- * using the {@link DataLine#available available} method of the
- * DataLine interface. (While it is guaranteed that
- * this number of bytes can be written without blocking, there is no guarantee
- * that attempts to write additional data will block.)
+ * The number of bytes that can be written without blocking can be
+ * ascertained using the {@link DataLine#available available} method of the
+ * {@code DataLine} interface. (While it is guaranteed that this number of
+ * bytes can be written without blocking, there is no guarantee that
+ * attempts to write additional data will block.)
*
- * The number of bytes to write must represent an integral number of
- * sample frames, such that:
+ * The number of bytes to write must represent an integral number of sample
+ * frames, such that:
*
- *
[ bytes written ] % [frame size in bytes ] == 0IllegalArgumentException.
+ * The return value will always meet this requirement. A request to write a
+ * number of bytes representing a non-integral number of sample frames
+ * cannot be fulfilled and may result in an
+ * {@code IllegalArgumentException}.
*
- * @param b a byte array containing data to be written to the data line
- * @param len the length, in bytes, of the valid data in the array
- * (in other words, the requested amount of data to write, in bytes)
- * @param off the offset from the beginning of the array, in bytes
+ * @param b a byte array containing data to be written to the data line
+ * @param len the length, in bytes, of the valid data in the array (in
+ * other words, the requested amount of data to write, in bytes)
+ * @param off the offset from the beginning of the array, in bytes
* @return the number of bytes actually written
* @throws IllegalArgumentException if the requested number of bytes does
- * not represent an integral number of sample frames,
- * or if len is negative
- * @throws ArrayIndexOutOfBoundsException if off is negative,
- * or off+len is greater than the length of the array
- * b.
- *
+ * not represent an integral number of sample frames, or if
+ * {@code len} is negative
+ * @throws ArrayIndexOutOfBoundsException if {@code off} is negative, or
+ * {@code off+len} is greater than the length of the array {@code b}
* @see TargetDataLine#read
* @see DataLine#available
*/
- public int write(byte[] b, int off, int len);
+ int write(byte[] b, int off, int len);
/**
* Obtains the number of sample frames of audio data that can be written to
- * the mixer, via this data line, without blocking. Note that the return
+ * the mixer, via this data line, without blocking. Note that the return
* value measures sample frames, not bytes.
+ *
* @return the number of sample frames currently available for writing
* @see TargetDataLine#availableRead
*/
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/TargetDataLine.java
--- a/jdk/src/share/classes/javax/sound/sampled/TargetDataLine.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/TargetDataLine.java Wed Jun 04 17:14:56 2014 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,29 +26,28 @@
package javax.sound.sampled;
/**
- * A target data line is a type of {@link DataLine} from which
- * audio data can be read. The most common example is a data line that gets
- * its data from an audio capture device. (The device is implemented as a
- * mixer that writes to the target data line.)
+ * A target data line is a type of {@link DataLine} from which audio data can be
+ * read. The most common example is a data line that gets its data from an audio
+ * capture device. (The device is implemented as a mixer that writes to the
+ * target data line.)
* * Note that the naming convention for this interface reflects the relationship - * between the line and its mixer. From the perspective of an application, - * a target data line may act as a source for audio data. + * between the line and its mixer. From the perspective of an application, a + * target data line may act as a source for audio data. *
* The target data line can be obtained from a mixer by invoking the
- * {@link Mixer#getLine getLine}
- * method of Mixer with an appropriate
- * {@link DataLine.Info} object.
+ * {@link Mixer#getLine getLine} method of {@code Mixer} with an appropriate
+ * {@link DataLine.Info} object.
*
- * The TargetDataLine interface provides a method for reading the
- * captured data from the target data line's buffer.Applications
- * that record audio should read data from the target data line quickly enough
- * to keep the buffer from overflowing, which could cause discontinuities in
- * the captured data that are perceived as clicks. Applications can use the
- * {@link DataLine#available available} method defined in the
- * DataLine interface to determine the amount of data currently
- * queued in the data line's buffer. If the buffer does overflow,
- * the oldest queued data is discarded and replaced by new data.
+ * The {@code TargetDataLine} interface provides a method for reading the
+ * captured data from the target data line's buffer. Applications that record
+ * audio should read data from the target data line quickly enough to keep the
+ * buffer from overflowing, which could cause discontinuities in the captured
+ * data that are perceived as clicks. Applications can use the
+ * {@link DataLine#available available} method defined in the {@code DataLine}
+ * interface to determine the amount of data currently queued in the data line's
+ * buffer. If the buffer does overflow, the oldest queued data is discarded and
+ * replaced by new data.
*
* @author Kara Kytle
* @see Mixer
@@ -58,133 +57,126 @@
*/
public interface TargetDataLine extends DataLine {
-
/**
* Opens the line with the specified format and requested buffer size,
* causing the line to acquire any required system resources and become
* operational.
*
* The buffer size is specified in bytes, but must represent an integral
- * number of sample frames. Invoking this method with a requested buffer
+ * number of sample frames. Invoking this method with a requested buffer
* size that does not meet this requirement may result in an
- * IllegalArgumentException. The actual buffer size for the open line may
- * differ from the requested buffer size. The value actually set may be
- * queried by subsequently calling {@link DataLine#getBufferSize}
+ * {@code IllegalArgumentException}. The actual buffer size for the open
+ * line may differ from the requested buffer size. The value actually set
+ * may be queried by subsequently calling {@link DataLine#getBufferSize}
*
* If this operation succeeds, the line is marked as open, and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
- * line's listeners.
+ * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+ * listeners.
*
- * Invoking this method on a line that is already open is illegal
- * and may result in an IllegalStateException.
+ * Invoking this method on a line that is already open is illegal and may
+ * result in an {@code IllegalStateException}.
*
- * Some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * LineUnavailableException.
+ * Some lines, once closed, cannot be reopened. Attempts to reopen such a
+ * line will always result in a {@code LineUnavailableException}.
*
- * @param format the desired audio format
- * @param bufferSize the desired buffer size, in bytes.
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IllegalArgumentException if the buffer size does not represent
- * an integral number of sample frames,
- * or if format is not fully specified or invalid
+ * @param format the desired audio format
+ * @param bufferSize the desired buffer size, in bytes
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IllegalArgumentException if the buffer size does not represent an
+ * integral number of sample frames, or if {@code format} is not
+ * fully specified or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #open(AudioFormat)
* @see Line#open
* @see Line#close
* @see Line#isOpen
* @see LineEvent
*/
- public void open(AudioFormat format, int bufferSize) throws LineUnavailableException;
-
+ void open(AudioFormat format, int bufferSize) throws LineUnavailableException;
/**
* Opens the line with the specified format, causing the line to acquire any
* required system resources and become operational.
- *
*
* The implementation chooses a buffer size, which is measured in bytes but
- * which encompasses an integral number of sample frames. The buffer size
- * that the system has chosen may be queried by subsequently calling {@link DataLine#getBufferSize}
+ * which encompasses an integral number of sample frames. The buffer size
+ * that the system has chosen may be queried by subsequently calling
+ * {@link DataLine#getBufferSize}
*
* If this operation succeeds, the line is marked as open, and an
- * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
- * line's listeners.
+ * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+ * listeners.
*
- * Invoking this method on a line that is already open is illegal
- * and may result in an IllegalStateException.
+ * Invoking this method on a line that is already open is illegal and may
+ * result in an {@code IllegalStateException}.
*
- * Some lines, once closed, cannot be reopened. Attempts
- * to reopen such a line will always result in a
- * LineUnavailableException.
+ * Some lines, once closed, cannot be reopened. Attempts to reopen such a
+ * line will always result in a {@code LineUnavailableException}.
*
- * @param format the desired audio format
- * @throws LineUnavailableException if the line cannot be
- * opened due to resource restrictions
- * @throws IllegalArgumentException if format
- * is not fully specified or invalid
+ * @param format the desired audio format
+ * @throws LineUnavailableException if the line cannot be opened due to
+ * resource restrictions
+ * @throws IllegalArgumentException if {@code format} is not fully specified
+ * or invalid
* @throws IllegalStateException if the line is already open
- * @throws SecurityException if the line cannot be
- * opened due to security restrictions
- *
+ * @throws SecurityException if the line cannot be opened due to security
+ * restrictions
* @see #open(AudioFormat, int)
* @see Line#open
* @see Line#close
* @see Line#isOpen
* @see LineEvent
*/
- public void open(AudioFormat format) throws LineUnavailableException;
-
+ void open(AudioFormat format) throws LineUnavailableException;
/**
- * Reads audio data from the data line's input buffer. The requested
- * number of bytes is read into the specified array, starting at
- * the specified offset into the array in bytes. This method blocks until
- * the requested amount of data has been read. However, if the data line
- * is closed, stopped, drained, or flushed before the requested amount has
- * been read, the method no longer blocks, but returns the number of bytes
- * read thus far.
+ * Reads audio data from the data line's input buffer. The requested number
+ * of bytes is read into the specified array, starting at the specified
+ * offset into the array in bytes. This method blocks until the requested
+ * amount of data has been read. However, if the data line is closed,
+ * stopped, drained, or flushed before the requested amount has been read,
+ * the method no longer blocks, but returns the number of bytes read thus
+ * far.
*
* The number of bytes that can be read without blocking can be ascertained
- * using the {@link DataLine#available available} method of the
- * DataLine interface. (While it is guaranteed that
- * this number of bytes can be read without blocking, there is no guarantee
- * that attempts to read additional data will block.)
+ * using the {@link DataLine#available available} method of the
+ * {@code DataLine} interface. (While it is guaranteed that this number of
+ * bytes can be read without blocking, there is no guarantee that attempts
+ * to read additional data will block.)
*
* The number of bytes to be read must represent an integral number of
* sample frames, such that:
*
- *
[ bytes read ] % [frame size in bytes ] == 0len is negative.
- * @throws ArrayIndexOutOfBoundsException if off is negative,
- * or off+len is greater than the length of the array
- * b.
+ * not represent an integral number of sample frames, or if
+ * {@code len} is negative
+ * @throws ArrayIndexOutOfBoundsException if {@code off} is negative, or
+ * {@code off+len} is greater than the length of the array {@code b}
*
* @see SourceDataLine#write
* @see DataLine#available
*/
- public int read(byte[] b, int off, int len);
+ int read(byte[] b, int off, int len);
/**
* Obtains the number of sample frames of audio data that can be read from
- * the target data line without blocking. Note that the return value
+ * the target data line without blocking. Note that the return value
* measures sample frames, not bytes.
+ *
* @return the number of sample frames currently available for reading
* @see SourceDataLine#availableWrite
*/
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java
--- a/jdk/src/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java Wed Jun 04 17:14:56 2014 +0400
@@ -26,33 +26,32 @@
package javax.sound.sampled;
/**
- * An UnsupportedAudioFileException is an exception indicating that an
- * operation failed because a file did not contain valid data of a recognized file
- * type and format.
+ * An {@code UnsupportedAudioFileException} is an exception indicating that an
+ * operation failed because a file did not contain valid data of a recognized
+ * file type and format.
*
* @author Kara Kytle
* @since 1.3
*/
public class UnsupportedAudioFileException extends Exception {
+
private static final long serialVersionUID = -139127412623160368L;
/**
- * Constructs a UnsupportedAudioFileException that has
- * null as its error detail message.
+ * Constructs a {@code UnsupportedAudioFileException} that has {@code null}
+ * as its error detail message.
*/
public UnsupportedAudioFileException() {
-
super();
}
/**
- * Constructs a UnsupportedAudioFileException that has
- * the specified detail message.
+ * Constructs a {@code UnsupportedAudioFileException} that has the specified
+ * detail message.
*
- * @param message a string containing the error detail message
+ * @param message a string containing the error detail message
*/
- public UnsupportedAudioFileException(String message) {
-
+ public UnsupportedAudioFileException(final String message) {
super(message);
}
}
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/spi/AudioFileReader.java
--- a/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileReader.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileReader.java Wed Jun 04 17:14:56 2014 +0400
@@ -108,7 +108,7 @@
* @param stream the input stream from which the {@code AudioInputStream}
* should be constructed
* @return an {@code AudioInputStream} object based on the audio file data
- * contained in the input stream.
+ * contained in the input stream
* @throws UnsupportedAudioFileException if the stream does not point to
* valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
diff -r e92fa066b0e0 -r 2dfdfa369071 jdk/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java
--- a/jdk/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java Wed Jun 04 16:55:06 2014 +0400
+++ b/jdk/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java Wed Jun 04 17:14:56 2014 +0400
@@ -117,7 +117,7 @@
* are supported for this source format, an array of length 0 is returned.
*
* @param sourceFormat format of the incoming data
- * @return array of supported target format encodings.
+ * @return array of supported target format encodings
*/
public abstract Encoding[] getTargetEncodings(AudioFormat sourceFormat);
@@ -150,7 +150,7 @@
*
* @param targetEncoding desired encoding of the stream after processing
* @param sourceFormat format of the incoming data
- * @return array of supported target formats.
+ * @return array of supported target formats
*/
public abstract AudioFormat[] getTargetFormats(Encoding targetEncoding,
AudioFormat sourceFormat);
@@ -187,7 +187,7 @@
* @return stream from which processed data with the specified target
* encoding may be read
* @throws IllegalArgumentException if the format combination supplied is
- * not supported.
+ * not supported
*/
public abstract AudioInputStream getAudioInputStream(
Encoding targetEncoding, AudioInputStream sourceStream);
@@ -202,7 +202,7 @@
* @return stream from which processed data with the specified format may be
* read
* @throws IllegalArgumentException if the format combination supplied is
- * not supported.
+ * not supported
*/
public abstract AudioInputStream getAudioInputStream(
AudioFormat targetFormat, AudioInputStream sourceStream);