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