jdk/src/share/classes/javax/sound/sampled/DataLine.java
author prr
Wed, 18 Jun 2014 13:14:15 -0700
changeset 25144 e2bf17cee34b
parent 25128 2dfdfa369071
parent 24969 afa6934dd8e8
child 26003 d630c97424bd
permissions -rw-r--r--
Merge
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
     2
 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package javax.sound.sampled;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
19368
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
    28
import java.util.Arrays;
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
    29
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
/**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    31
 * {@code DataLine} adds media-related functionality to its superinterface,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    32
 * {@code Line}. This functionality includes transport-control methods that
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    33
 * start, stop, drain, and flush the audio data that passes through the line. A
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    34
 * data line can also report the current position, volume, and audio format of
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    35
 * the media. Data lines are used for output of audio by means of the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    36
 * subinterfaces {@link SourceDataLine} or {@link Clip}, which allow an
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    37
 * application program to write data. Similarly, audio input is handled by the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    38
 * subinterface {@link TargetDataLine}, which allows data to be read.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * <p>
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    40
 * A data line has an internal buffer in which the incoming or outgoing audio
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    41
 * data is queued. The {@link #drain()} method blocks until this internal buffer
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    42
 * becomes empty, usually because all queued data has been processed. The
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    43
 * {@link #flush()} method discards any available queued data from the internal
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    44
 * buffer.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * <p>
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    46
 * A data line produces {@link LineEvent.Type#START START} and
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    47
 * {@link LineEvent.Type#STOP STOP} events whenever it begins or ceases active
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    48
 * presentation or capture of data. These events can be generated in response to
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    49
 * specific requests, or as a result of less direct state changes. For example,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    50
 * if {@link #start()} is called on an inactive data line, and data is available
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    51
 * for capture or playback, a {@code START} event will be generated shortly,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    52
 * when data playback or capture actually begins. Or, if the flow of data to an
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    53
 * active data line is constricted so that a gap occurs in the presentation of
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    54
 * data, a {@code STOP} event is generated.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * Mixers often support synchronized control of multiple data lines.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * Synchronization can be established through the Mixer interface's
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    58
 * {@link Mixer#synchronize synchronize} method. See the description of the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    59
 * {@link Mixer Mixer} interface for a more complete description.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * @author Kara Kytle
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * @see LineEvent
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 * @since 1.3
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
public interface DataLine extends Line {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    68
     * Drains queued data from the line by continuing data I/O until the data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    69
     * line's internal buffer has been emptied. This method blocks until the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    70
     * draining is complete. Because this is a blocking method, it should be
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    71
     * used with care. If {@code drain()} is invoked on a stopped line that has
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    72
     * data in its queue, the method will block until the line is running and
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    73
     * the data queue becomes empty. If {@code drain()} is invoked by one
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    74
     * thread, and another continues to fill the data queue, the operation will
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    75
     * not complete. This method always returns when the data line is closed.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
     * @see #flush()
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    79
    void drain();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    82
     * Flushes queued data from the line. The flushed data is discarded. In some
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    83
     * cases, not all queued data can be discarded. For example, a mixer can
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    84
     * flush data from the buffer for a specific input line, but any unplayed
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    85
     * data already in the output buffer (the result of the mix) will still be
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    86
     * played. You can invoke this method after pausing a line (the normal case)
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    87
     * if you want to skip the "stale" data when you restart playback or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    88
     * capture. (It is legal to flush a line that is not stopped, but doing so
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    89
     * on an active line is likely to cause a discontinuity in the data,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    90
     * resulting in a perceptible click.)
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
     * @see #stop()
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
     * @see #drain()
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    95
    void flush();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    98
     * Allows a line to engage in data I/O. If invoked on a line that is already
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
    99
     * running, this method does nothing. Unless the data in the buffer has been
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   100
     * flushed, the line resumes I/O starting with the first frame that was
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   101
     * unprocessed at the time the line was stopped. When audio capture or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   102
     * playback starts, a {@link LineEvent.Type#START START} event is generated.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
     * @see #stop()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
     * @see #isRunning()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
     * @see LineEvent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   108
    void start();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   111
     * Stops the line. A stopped line should cease I/O activity. If the line is
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   112
     * open and running, however, it should retain the resources required to
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   113
     * resume activity. A stopped line should retain any audio data in its
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   114
     * buffer instead of discarding it, so that upon resumption the I/O can
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   115
     * continue where it left off, if possible. (This doesn't guarantee that
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   116
     * there will never be discontinuities beyond the current buffer, of course;
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   117
     * if the stopped condition continues for too long, input or output samples
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   118
     * might be dropped.) If desired, the retained data can be discarded by
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   119
     * invoking the {@code flush} method. When audio capture or playback stops,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   120
     * a {@link LineEvent.Type#STOP STOP} event is generated.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
     * @see #start()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     * @see #isRunning()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     * @see #flush()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
     * @see LineEvent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   127
    void stop();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   130
     * Indicates whether the line is running. The default is {@code false}. An
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   131
     * open line begins running when the first data is presented in response to
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   132
     * an invocation of the {@code start} method, and continues until
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   133
     * presentation ceases in response to a call to {@code stop} or because
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   134
     * playback completes.
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   135
     *
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   136
     * @return {@code true} if the line is running, otherwise {@code false}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
     * @see #start()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
     * @see #stop()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   140
    boolean isRunning();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   143
     * Indicates whether the line is engaging in active I/O (such as playback or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   144
     * capture). When an inactive line becomes active, it sends a
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   145
     * {@link LineEvent.Type#START START} event to its listeners. Similarly,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   146
     * when an active line becomes inactive, it sends a
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   147
     * {@link LineEvent.Type#STOP STOP} event.
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   148
     *
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   149
     * @return {@code true} if the line is actively capturing or rendering
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   150
     *         sound, otherwise {@code false}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
     * @see #isOpen
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
     * @see #addLineListener
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * @see #removeLineListener
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     * @see LineEvent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
     * @see LineListener
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   157
    boolean isActive();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * Obtains the current format (encoding, sample rate, number of channels,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     * etc.) of the data line's audio data.
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   162
     * <p>
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   163
     * If the line is not open and has never been opened, it returns the default
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   164
     * format. The default format is an implementation specific audio format,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   165
     * or, if the {@code DataLine.Info} object, which was used to retrieve this
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   166
     * {@code DataLine}, specifies at least one fully qualified audio format,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   167
     * the last one will be used as the default format. Opening the line with a
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   168
     * specific audio format (e.g. {@link SourceDataLine#open(AudioFormat)})
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   169
     * will override the default format.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     * @return current audio data format
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     * @see AudioFormat
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   174
    AudioFormat getFormat();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   177
     * Obtains the maximum number of bytes of data that will fit in the data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   178
     * line's internal buffer. For a source data line, this is the size of the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   179
     * buffer to which data can be written. For a target data line, it is the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   180
     * size of the buffer from which data can be read. Note that the units used
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   181
     * are bytes, but will always correspond to an integral number of sample
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   182
     * frames of audio data.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
     * @return the size of the buffer in bytes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   186
    int getBufferSize();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
     * Obtains the number of bytes of data currently available to the
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   190
     * application for processing in the data line's internal buffer. For a
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
     * source data line, this is the amount of data that can be written to the
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   192
     * buffer without blocking. For a target data line, this is the amount of
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   193
     * data available to be read by the application. For a clip, this value is
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   194
     * always 0 because the audio data is loaded into the buffer when the clip
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   195
     * is opened, and persists without modification until the clip is closed.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
     * <p>
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   197
     * Note that the units used are bytes, but will always correspond to an
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   198
     * integral number of sample frames of audio data.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
     * <p>
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   200
     * An application is guaranteed that a read or write operation of up to the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   201
     * number of bytes returned from {@code available()} will not block;
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   202
     * however, there is no guarantee that attempts to read or write more data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   203
     * will block.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
     * @return the amount of data available, in bytes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   207
    int available();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   210
     * Obtains the current position in the audio data, in sample frames. The
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   211
     * frame position measures the number of sample frames captured by, or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   212
     * rendered from, the line since it was opened. This return value will wrap
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   213
     * around after 2^31 frames. It is recommended to use
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   214
     * {@code getLongFramePosition} instead.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
     * @return the number of frames already processed since the line was opened
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
     * @see #getLongFramePosition()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   219
    int getFramePosition();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   222
     * Obtains the current position in the audio data, in sample frames. The
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   223
     * frame position measures the number of sample frames captured by, or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   224
     * rendered from, the line since it was opened.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
     * @return the number of frames already processed since the line was opened
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
     * @since 1.5
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   229
    long getLongFramePosition();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   232
     * Obtains the current position in the audio data, in microseconds. The
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   233
     * microsecond position measures the time corresponding to the number of
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   234
     * sample frames captured by, or rendered from, the line since it was
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   235
     * opened. The level of precision is not guaranteed. For example, an
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   236
     * implementation might calculate the microsecond position from the current
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   237
     * frame position and the audio sample frame rate. The precision in
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   238
     * microseconds would then be limited to the number of microseconds per
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   239
     * sample frame.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
     *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   241
     * @return the number of microseconds of data processed since the line was
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   242
     *         opened
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   244
    long getMicrosecondPosition();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
    /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   247
     * Obtains the current volume level for the line. This level is a measure of
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   248
     * the signal's current amplitude, and should not be confused with the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   249
     * current setting of a gain control. The range is from 0.0 (silence) to 1.0
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   250
     * (maximum possible amplitude for the sound waveform). The units measure
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   251
     * linear amplitude, not decibels.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
     * @return the current amplitude of the signal in this line, or
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   254
     *         {@link AudioSystem#NOT_SPECIFIED}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   256
    float getLevel();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
     * Besides the class information inherited from its superclass,
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   260
     * {@code DataLine.Info} provides additional information specific to data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   261
     * lines. This information includes:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
     * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
     * <li> the audio formats supported by the data line
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
     * <li> the minimum and maximum sizes of its internal buffer
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
     * </ul>
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   266
     * Because a {@code Line.Info} knows the class of the line its describes, a
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   267
     * {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   268
     * such as {@link SourceDataLine}, {@link TargetDataLine}, and {@link Clip}.
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   269
     * You can query a mixer for lines of any of these types, passing an
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   270
     * appropriate instance of {@code DataLine.Info} as the argument to a method
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   271
     * such as {@link Mixer#getLine(Line.Info)}.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
     * @see Line.Info
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
     * @author Kara Kytle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
     * @since 1.3
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
     */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   277
    class Info extends Line.Info {
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
19368
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   279
        private final AudioFormat[] formats;
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   280
        private final int minBufferSize;
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   281
        private final int maxBufferSize;
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
         * Constructs a data line's info object from the specified information,
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   285
         * which includes a set of supported audio formats and a range for the
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   286
         * buffer size. This constructor is typically used by mixer
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   287
         * implementations when returning information about a supported line.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
         *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   289
         * @param  lineClass the class of the data line described by the info
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   290
         *         object
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   291
         * @param  formats set of formats supported
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   292
         * @param  minBufferSize minimum buffer size supported by the data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   293
         *         line, in bytes
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   294
         * @param  maxBufferSize maximum buffer size supported by the data
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   295
         *         line, in bytes
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
        public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
            super(lineClass);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
            if (formats == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
                this.formats = new AudioFormat[0];
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
            } else {
19368
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   304
                this.formats = Arrays.copyOf(formats, formats.length);
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
            this.minBufferSize = minBufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
            this.maxBufferSize = maxBufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
         * Constructs a data line's info object from the specified information,
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   313
         * which includes a single audio format and a desired buffer size. This
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   314
         * constructor is typically used by an application to describe a desired
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   315
         * line.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
         *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   317
         * @param  lineClass the class of the data line described by the info
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   318
         *         object
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   319
         * @param  format desired format
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   320
         * @param  bufferSize desired buffer size in bytes
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
        public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
            super(lineClass);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
90ce3da70b43 Initial load
duke
parents:
diff changeset
   326
            if (format == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
                this.formats = new AudioFormat[0];
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
            } else {
19368
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   329
                this.formats = new AudioFormat[]{format};
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   330
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   331
90ce3da70b43 Initial load
duke
parents:
diff changeset
   332
            this.minBufferSize = bufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   333
            this.maxBufferSize = bufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   334
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   335
90ce3da70b43 Initial load
duke
parents:
diff changeset
   336
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   337
         * Constructs a data line's info object from the specified information,
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   338
         * which includes a single audio format. This constructor is typically
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   339
         * used by an application to describe a desired line.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   340
         *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   341
         * @param  lineClass the class of the data line described by the info
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   342
         *         object
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   343
         * @param  format desired format
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   344
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   345
        public Info(Class<?> lineClass, AudioFormat format) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   346
            this(lineClass, format, AudioSystem.NOT_SPECIFIED);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   347
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   348
90ce3da70b43 Initial load
duke
parents:
diff changeset
   349
        /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   350
         * Obtains a set of audio formats supported by the data line. Note that
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   351
         * {@code isFormatSupported(AudioFormat)} might return {@code true} for
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   352
         * certain additional formats that are missing from the set returned by
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   353
         * {@code getFormats()}. The reverse is not the case:
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   354
         * {@code isFormatSupported(AudioFormat)} is guaranteed to return
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   355
         * {@code true} for all formats returned by {@code getFormats()}.
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   356
         * <p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   357
         * Some fields in the AudioFormat instances can be set to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   358
         * {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED NOT_SPECIFIED}
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   359
         * if that field does not apply to the format, or if the format supports
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   360
         * a wide range of values for that field. For example, a multi-channel
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   361
         * device supporting up to 64 channels, could set the channel field in
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   362
         * the {@code AudioFormat} instances returned by this method to
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   363
         * {@code NOT_SPECIFIED}.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   364
         *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   365
         * @return a set of supported audio formats
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   366
         * @see #isFormatSupported(AudioFormat)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   367
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   368
        public AudioFormat[] getFormats() {
19368
5d7565f5978c 8006085: [findbugs] a warning on javax.sound.sampled.DataLine$Info constructor
serb
parents: 5506
diff changeset
   369
            return Arrays.copyOf(formats, formats.length);
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   370
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   371
90ce3da70b43 Initial load
duke
parents:
diff changeset
   372
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   373
         * Indicates whether this data line supports a particular audio format.
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   374
         * The default implementation of this method simply returns {@code true}
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   375
         * if the specified format matches any of the supported formats.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   376
         *
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   377
         * @param  format the audio format for which support is queried
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   378
         * @return {@code true} if the format is supported, otherwise
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   379
         *         {@code false}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   380
         * @see #getFormats
90ce3da70b43 Initial load
duke
parents:
diff changeset
   381
         * @see AudioFormat#matches
90ce3da70b43 Initial load
duke
parents:
diff changeset
   382
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   383
        public boolean isFormatSupported(AudioFormat format) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   384
90ce3da70b43 Initial load
duke
parents:
diff changeset
   385
            for (int i = 0; i < formats.length; i++) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   386
                if (format.matches(formats[i])) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   387
                    return true;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   388
                }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   389
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   390
90ce3da70b43 Initial load
duke
parents:
diff changeset
   391
            return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   392
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   393
90ce3da70b43 Initial load
duke
parents:
diff changeset
   394
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   395
         * Obtains the minimum buffer size supported by the data line.
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   396
         *
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   397
         * @return minimum buffer size in bytes, or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   398
         *         {@code AudioSystem.NOT_SPECIFIED}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   399
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   400
        public int getMinBufferSize() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   401
            return minBufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   402
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   403
90ce3da70b43 Initial load
duke
parents:
diff changeset
   404
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   405
         * Obtains the maximum buffer size supported by the data line.
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   406
         *
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   407
         * @return maximum buffer size in bytes, or
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   408
         *         {@code AudioSystem.NOT_SPECIFIED}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   409
         */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   410
        public int getMaxBufferSize() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   411
            return maxBufferSize;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   412
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   413
90ce3da70b43 Initial load
duke
parents:
diff changeset
   414
        /**
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   415
         * Determines whether the specified info object matches this one. To
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   416
         * match, the superclass match requirements must be met. In addition,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   417
         * this object's minimum buffer size must be at least as large as that
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   418
         * of the object specified, its maximum buffer size must be at most as
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   419
         * large as that of the object specified, and all of its formats must
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   420
         * match formats supported by the object specified.
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   421
         *
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   422
         * @return {@code true} if this object matches the one specified,
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   423
         *         otherwise {@code false}
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   424
         */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   425
        @Override
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   426
        public boolean matches(Line.Info info) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   427
90ce3da70b43 Initial load
duke
parents:
diff changeset
   428
            if (! (super.matches(info)) ) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   429
                return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   430
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   431
90ce3da70b43 Initial load
duke
parents:
diff changeset
   432
            Info dataLineInfo = (Info)info;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   433
90ce3da70b43 Initial load
duke
parents:
diff changeset
   434
            // treat anything < 0 as NOT_SPECIFIED
90ce3da70b43 Initial load
duke
parents:
diff changeset
   435
            // demo code in old Java Sound Demo used a wrong buffer calculation
90ce3da70b43 Initial load
duke
parents:
diff changeset
   436
            // that would lead to arbitrary negative values
90ce3da70b43 Initial load
duke
parents:
diff changeset
   437
            if ((getMaxBufferSize() >= 0) && (dataLineInfo.getMaxBufferSize() >= 0)) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   438
                if (getMaxBufferSize() > dataLineInfo.getMaxBufferSize()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   439
                    return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   440
                }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   441
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   442
90ce3da70b43 Initial load
duke
parents:
diff changeset
   443
            if ((getMinBufferSize() >= 0) && (dataLineInfo.getMinBufferSize() >= 0)) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   444
                if (getMinBufferSize() < dataLineInfo.getMinBufferSize()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   445
                    return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   446
                }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   447
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   448
90ce3da70b43 Initial load
duke
parents:
diff changeset
   449
            AudioFormat[] localFormats = getFormats();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   450
90ce3da70b43 Initial load
duke
parents:
diff changeset
   451
            if (localFormats != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   452
90ce3da70b43 Initial load
duke
parents:
diff changeset
   453
                for (int i = 0; i < localFormats.length; i++) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   454
                    if (! (localFormats[i] == null) ) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   455
                        if (! (dataLineInfo.isFormatSupported(localFormats[i])) ) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   456
                            return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   457
                        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   458
                    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   459
                }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   460
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   461
90ce3da70b43 Initial load
duke
parents:
diff changeset
   462
            return true;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   463
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   464
90ce3da70b43 Initial load
duke
parents:
diff changeset
   465
        /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   466
         * Obtains a textual description of the data line info.
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   467
         *
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   468
         * @return a string description
90ce3da70b43 Initial load
duke
parents:
diff changeset
   469
         */
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   470
        @Override
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   471
        public String toString() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   472
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   473
            StringBuilder sb = new StringBuilder();
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   474
90ce3da70b43 Initial load
duke
parents:
diff changeset
   475
            if ( (formats.length == 1) && (formats[0] != null) ) {
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   476
                sb.append(" supporting format " + formats[0]);
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   477
            } else if (getFormats().length > 1) {
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   478
                sb.append(" supporting " + getFormats().length + " audio formats");
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   479
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   480
90ce3da70b43 Initial load
duke
parents:
diff changeset
   481
            if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (maxBufferSize != AudioSystem.NOT_SPECIFIED) ) {
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   482
                sb.append(", and buffers of " + minBufferSize + " to " + maxBufferSize + " bytes");
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   483
            } else if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (minBufferSize > 0) ) {
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   484
                sb.append(", and buffers of at least " + minBufferSize + " bytes");
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   485
            } else if (maxBufferSize != AudioSystem.NOT_SPECIFIED) {
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   486
                sb.append(", and buffers of up to " + minBufferSize + " bytes");
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   487
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   488
24969
afa6934dd8e8 8041679: Replace uses of StringBuffer with StringBuilder within core library classes
psandoz
parents: 23010
diff changeset
   489
            return new String(super.toString() + sb);
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   490
        }
25128
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   491
    }
2dfdfa369071 8043979: Javadoc cleanup of javax.sound.sampled package
serb
parents: 23010
diff changeset
   492
}