--- 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;
/**
- * <code>DataLine</code> adds media-related functionality to its
- * superinterface, <code>{@link Line}</code>. 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 <code>{@link SourceDataLine}</code> or
- * <code>{@link Clip}</code>, which allow an application program to write data. Similarly,
- * audio input is handled by the subinterface <code>{@link TargetDataLine}</code>,
- * 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.
* <p>
- * A data line has an internal buffer in which
- * the incoming or outgoing audio data is queued. The
- * <code>{@link #drain()}</code> method blocks until this internal buffer
- * becomes empty, usually because all queued data has been processed. The
- * <code>{@link #flush()}</code> 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.
* <p>
- * A data line produces <code>{@link LineEvent.Type#START START}</code> and
- * <code>{@link LineEvent.Type#STOP STOP}</code> 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 <code>{@link #start()}</code> is called
- * on an inactive data line, and data is available for capture or playback, a
- * <code>START</code> 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</code> 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.
* <p>
* Mixers often support synchronized control of multiple data lines.
* Synchronization can be established through the Mixer interface's
- * <code>{@link Mixer#synchronize synchronize}</code> method.
- * See the description of the <code>{@link Mixer Mixer}</code> 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 <code>drain()</code>
- * 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()</code> 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
- * <code>{@link LineEvent.Type#START START}</code> 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 <code>flush</code> method.
- * When audio capture or playback stops, a <code>{@link LineEvent.Type#STOP STOP}</code> 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 <code>false</code>.
- * An open line begins running when the first data is presented in response to an
- * invocation of the <code>start</code> method, and continues
- * until presentation ceases in response to a call to <code>stop</code> or
- * because playback completes.
- * @return <code>true</code> if the line is running, otherwise <code>false</code>
+ * 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
- * <code>{@link LineEvent.Type#START START}</code> event to its listeners. Similarly, when
- * an active line becomes inactive, it sends a
- * <code>{@link LineEvent.Type#STOP STOP}</code> event.
- * @return <code>true</code> if the line is actively capturing or rendering
- * sound, otherwise <code>false</code>
+ * 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.
- *
- * <p>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</code>
- * object, which was used to retrieve this <code>DataLine</code>,
- * 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.
+ * <p>
+ * 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.
* <p>
- * 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.
* <p>
- * An application is guaranteed that a read or
- * write operation of up to the number of bytes returned from
- * <code>available()</code> 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 <code>getLongFramePosition</code> 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
- * <code>{@link AudioSystem#NOT_SPECIFIED}</code>
+ * {@link AudioSystem#NOT_SPECIFIED}
*/
- public float getLevel();
+ float getLevel();
/**
* Besides the class information inherited from its superclass,
- * <code>DataLine.Info</code> provides additional information specific to data lines.
- * This information includes:
+ * {@code DataLine.Info} provides additional information specific to data
+ * lines. This information includes:
* <ul>
* <li> the audio formats supported by the data line
* <li> the minimum and maximum sizes of its internal buffer
* </ul>
- * Because a <code>Line.Info</code> knows the class of the line its describes, a
- * <code>DataLine.Info</code> object can describe <code>DataLine</code>
- * subinterfaces such as <code>{@link SourceDataLine}</code>,
- * <code>{@link TargetDataLine}</code>, and <code>{@link Clip}</code>.
- * You can query a mixer for lines of any of these types, passing an appropriate
- * instance of <code>DataLine.Info</code> as the argument to a method such as
- * <code>{@link Mixer#getLine Mixer.getLine(Line.Info)}</code>.
+ * 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 <code>isFormatSupported(AudioFormat)</code> might return
- * <code>true</code> for certain additional formats that are missing from
- * the set returned by <code>getFormats()</code>. The reverse is not
- * the case: <code>isFormatSupported(AudioFormat)</code> is guaranteed to return
- * <code>true</code> for all formats returned by <code>getFormats()</code>.
- *
+ * 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()}.
+ * <p>
* 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
- * <code>AudioFormat</code> instances returned by this
- * method to <code>NOT_SPECIFIED</code>.
+ * 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 <code>true</code> 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 <code>true</code> if the format is supported, otherwise <code>false</code>
+ * @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 <code>AudioSystem.NOT_SPECIFIED</code>
+ *
+ * @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 <code>AudioSystem.NOT_SPECIFIED</code>
+ *
+ * @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 <code>true</code> if this object matches the one specified,
- * otherwise <code>false</code>.
+ * 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
+ }
+}