* Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.

 * {@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 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.

 * {@link Mixer#synchronize synchronize} method. See the description of the

 * {@link Mixer Mixer} interface for a more complete description.

     * 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.

    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.)

    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.

    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} method. When audio capture or playback stops,

     * a {@link LineEvent.Type#STOP STOP} event is generated.

    void stop();

     * 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}

    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 {@code true} if the line is actively capturing or rendering

     *         sound, otherwise {@code false}

    boolean isActive();

     * <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.

    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.

    int getBufferSize();

     * application for processing in the data line's internal buffer. For a

     * 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.

     * 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.

    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} instead.

    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.

    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.

     * @return the number of microseconds of data processed since the line was

     *         opened

    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.

     *         {@link AudioSystem#NOT_SPECIFIED}

    float getLevel();

     * {@code DataLine.Info} provides additional information specific to data

     * lines. This information includes:

     * 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)}.

    class Info extends Line.Info {

         * 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

         * 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

         * 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

         * 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>

         * 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

         * 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} if the format is supported, otherwise

         *         {@code false}

         *

         * @return minimum buffer size in bytes, or

         *         {@code AudioSystem.NOT_SPECIFIED}

         *

         * @return maximum buffer size in bytes, or

         *         {@code AudioSystem.NOT_SPECIFIED}

         * 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

         *

        @Override

    }

}