AutoCloseable
Clip
, DataLine
, Mixer
, Port
, SourceDataLine
, TargetDataLine
public interface Line extends AutoCloseable
Line
interface represents a mono or multi-channel audio feed. A line is an element of the digital audio "pipeline," such as a mixer, an input or output port, or a data path into or out of a mixer. A line can have controls, such as gain, pan, and reverb. The controls themselves are instances of classes that extend the base Control
class. The Line
interface provides two accessor methods for obtaining the line's controls: getControls
returns the entire set, and getControl
returns a single control of specified type.
Lines exist in various states at different times. When a line opens, it reserves system resources for itself, and when it closes, these resources are freed for other objects or applications. The isOpen()
method lets you discover whether a line is open or closed. An open line need not be processing data, however. Such processing is typically initiated by subinterface methods such as SourceDataLine.write
and TargetDataLine.read
.
You can register an object to receive notifications whenever the line's state changes. The object must implement the LineListener
interface, which consists of the single method update
. This method will be invoked when a line opens and closes (and, if it's a DataLine
, when it starts and stops).
An object can be registered to listen to multiple lines. The event it receives in its update
method will specify which line created the event, what type of event it was (OPEN
, CLOSE
, START
, or STOP
), and how many sample frames the line had processed at the time the event occurred.
Certain line operations, such as open and close, can generate security exceptions if invoked by unprivileged code when the line is a shared audio resource.
Modifier and Type | Interface | Description |
---|---|---|
static class |
Line.Info |
A Line.Info object contains information about a line. |
Modifier and Type | Method | Description |
---|---|---|
void |
addLineListener |
Adds a listener to this line. |
void |
close() |
Closes the line, indicating that any system resources in use by the line can be released. |
Control |
getControl |
Obtains a control of the specified type, if there is any. |
Control[] |
getControls() |
Obtains the set of controls associated with this line. |
Line.Info |
getLineInfo() |
Obtains the Line.Info object describing this line. |
boolean |
isControlSupported |
Indicates whether the line supports a control of the specified type. |
boolean |
isOpen() |
Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound. |
void |
open() |
Opens the line, indicating that it should acquire any required system resources and become operational. |
void |
removeLineListener |
Removes the specified listener from this line's list of listeners. |
Line.Info getLineInfo()
Line.Info
object describing this line.void open() throws LineUnavailableException
OPEN
event is dispatched to the line's listeners. Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in an LineUnavailableException
.
Some types of lines have configurable properties that may affect resource allocation. For example, a DataLine
must be opened with a particular format and buffer size. Such lines should provide a mechanism for configuring these properties, such as an additional open
method or methods which allow an application to specify the desired settings.
This method takes no arguments, and opens the line with the current settings. For SourceDataLine
and TargetDataLine
objects, this means that the line is opened with default settings. For a Clip
, however, the buffer size is determined when data is loaded. Since this method does not allow the application to specify any data to load, an IllegalArgumentException
is thrown. Therefore, you should instead use one of the open
methods provided in the Clip
interface to load data into the Clip
.
For DataLine
's, if the DataLine.Info
object which was used to retrieve the line, specifies at least one fully qualified audio format, the last one will be used as the default format.
IllegalArgumentException
- if this method is called on a Clip instanceLineUnavailableException
- if the line cannot be opened due to resource restrictionsSecurityException
- if the line cannot be opened due to security restrictionsvoid close()
CLOSE
event is dispatched to the line's listeners.close
in interface AutoCloseable
SecurityException
- if the line cannot be closed due to security restrictionsboolean isOpen()
true
if the line is open, otherwise false
Control[] getControls()
boolean isControlSupported(Control.Type control)
control
- the type of the control for which support is queriedtrue
if at least one control of the specified type is supported, otherwise false
Control getControl(Control.Type control)
control
- the type of the requested controlIllegalArgumentException
- if a control of the specified type is not supportedvoid addLineListener(LineListener listener)
update()
method is called with a LineEvent
object that describes the change.listener
- the object to add as a listener to this linevoid removeLineListener(LineListener listener)
listener
- listener to remove
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/sound/sampled/Line.html