1 /*
2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.sampled;
27
28 /**
29 * A target data line is a type of {@link DataLine} from which audio data can be
30 * read. The most common example is a data line that gets its data from an audio
31 * capture device. (The device is implemented as a mixer that writes to the
32 * target data line.)
33 * <p>
34 * Note that the naming convention for this interface reflects the relationship
35 * between the line and its mixer. From the perspective of an application, a
36 * target data line may act as a source for audio data.
37 * <p>
38 * The target data line can be obtained from a mixer by invoking the
39 * {@link Mixer#getLine getLine} method of {@code Mixer} with an appropriate
40 * {@link DataLine.Info} object.
41 * <p>
42 * The {@code TargetDataLine} interface provides a method for reading the
43 * captured data from the target data line's buffer. Applications that record
44 * audio should read data from the target data line quickly enough to keep the
45 * buffer from overflowing, which could cause discontinuities in the captured
46 * data that are perceived as clicks. Applications can use the
47 * {@link DataLine#available available} method defined in the {@code DataLine}
48 * interface to determine the amount of data currently queued in the data line's
49 * buffer. If the buffer does overflow, the oldest queued data is discarded and
50 * replaced by new data.
51 *
52 * @author Kara Kytle
53 * @see Mixer
54 * @see DataLine
55 * @see SourceDataLine
56 * @since 1.3
57 */
58 public interface TargetDataLine extends DataLine {
59
60 /**
61 * Opens the line with the specified format and requested buffer size,
62 * causing the line to acquire any required system resources and become
63 * operational.
64 * <p>
65 * The buffer size is specified in bytes, but must represent an integral
66 * number of sample frames. Invoking this method with a requested buffer
67 * size that does not meet this requirement may result in an
68 * {@code IllegalArgumentException}. The actual buffer size for the open
69 * line may differ from the requested buffer size. The value actually set
70 * may be queried by subsequently calling {@link DataLine#getBufferSize}
71 * <p>
72 * If this operation succeeds, the line is marked as open, and an
73 * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
74 * listeners.
75 * <p>
76 * Invoking this method on a line that is already open is illegal and may
77 * result in an {@code IllegalStateException}.
78 * <p>
79 * Some lines, once closed, cannot be reopened. Attempts to reopen such a
80 * line will always result in a {@code LineUnavailableException}.
81 *
82 * @param format the desired audio format
83 * @param bufferSize the desired buffer size, in bytes
84 * @throws LineUnavailableException if the line cannot be opened due to
85 * resource restrictions
86 * @throws IllegalArgumentException if the buffer size does not represent an
87 * integral number of sample frames, or if {@code format} is not
88 * fully specified or invalid
89 * @throws IllegalStateException if the line is already open
90 * @throws SecurityException if the line cannot be opened due to security
91 * restrictions
92 * @see #open(AudioFormat)
93 * @see Line#open
94 * @see Line#close
95 * @see Line#isOpen
96 * @see LineEvent
97 */
98 void open(AudioFormat format, int bufferSize) throws LineUnavailableException;
99
100 /**
101 * Opens the line with the specified format, causing the line to acquire any
102 * required system resources and become operational.
103 * <p>
104 * The implementation chooses a buffer size, which is measured in bytes but
105 * which encompasses an integral number of sample frames. The buffer size
106 * that the system has chosen may be queried by subsequently calling
107 * {@link DataLine#getBufferSize}
108 * <p>
109 * If this operation succeeds, the line is marked as open, and an
110 * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
111 * listeners.
112 * <p>
113 * Invoking this method on a line that is already open is illegal and may
114 * result in an {@code IllegalStateException}.
115 * <p>
116 * Some lines, once closed, cannot be reopened. Attempts to reopen such a
117 * line will always result in a {@code LineUnavailableException}.
118 *
119 * @param format the desired audio format
120 * @throws LineUnavailableException if the line cannot be opened due to
121 * resource restrictions
122 * @throws IllegalArgumentException if {@code format} is not fully specified
123 * or invalid
124 * @throws IllegalStateException if the line is already open
125 * @throws SecurityException if the line cannot be opened due to security
126 * restrictions
127 * @see #open(AudioFormat, int)
128 * @see Line#open
129 * @see Line#close
130 * @see Line#isOpen
131 * @see LineEvent
132 */
133 void open(AudioFormat format) throws LineUnavailableException;
134
135 /**
136 * Reads audio data from the data line's input buffer. The requested number
137 * of bytes is read into the specified array, starting at the specified
138 * offset into the array in bytes. This method blocks until the requested
139 * amount of data has been read. However, if the data line is closed,
140 * stopped, drained, or flushed before the requested amount has been read,
141 * the method no longer blocks, but returns the number of bytes read thus
142 * far.
143 * <p>
144 * The number of bytes that can be read without blocking can be ascertained
145 * using the {@link DataLine#available available} method of the
146 * {@code DataLine} interface. (While it is guaranteed that this number of
147 * bytes can be read without blocking, there is no guarantee that attempts
148 * to read additional data will block.)
149 * <p>
150 * The number of bytes to be read must represent an integral number of
151 * sample frames, such that:
152 * <br>
153 * <center>{@code [ bytes read ] % [frame size in bytes ] == 0}</center>
154 * <br>
155 * The return value will always meet this requirement. A request to read a
156 * number of bytes representing a non-integral number of sample frames
157 * cannot be fulfilled and may result in an IllegalArgumentException.
158 *
159 * @param b a byte array that will contain the requested input data when
160 * this method returns
161 * @param off the offset from the beginning of the array, in bytes
162 * @param len the requested number of bytes to read
163 * @return the number of bytes actually read
164 * @throws IllegalArgumentException if the requested number of bytes does
165 * not represent an integral number of sample frames, or if
166 * {@code len} is negative
167 * @throws ArrayIndexOutOfBoundsException if {@code off} is negative, or
168 * {@code off+len} is greater than the length of the array {@code b}
169 *
170 * @see SourceDataLine#write
171 * @see DataLine#available
172 */
173 int read(byte[] b, int off, int len);
174
175 /**
176 * Obtains the number of sample frames of audio data that can be read from
177 * the target data line without blocking. Note that the return value
178 * measures sample frames, not bytes.
179 *
180 * @return the number of sample frames currently available for reading
181 * @see SourceDataLine#availableWrite
182 */
183 //public int availableRead();
184 }