javax.sound.sampled
Interface Line

All Known Subinterfaces:
Clip sample code for javax.sound.sampled.Clip definition code for javax.sound.sampled.Clip , DataLine sample code for javax.sound.sampled.DataLine definition code for javax.sound.sampled.DataLine , Mixer sample code for javax.sound.sampled.Mixer definition code for javax.sound.sampled.Mixer , Port sample code for javax.sound.sampled.Port definition code for javax.sound.sampled.Port , SourceDataLine sample code for javax.sound.sampled.SourceDataLine definition code for javax.sound.sampled.SourceDataLine , TargetDataLine sample code for javax.sound.sampled.TargetDataLine definition code for javax.sound.sampled.TargetDataLine

public interface Line

The 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 sample code for javax.sound.sampled.Control definition code for javax.sound.sampled.Control class. The Line interface provides two accessor methods for obtaining the line's controls: getControls sample code for javax.sound.sampled.Line.getControls() definition code for javax.sound.sampled.Line.getControls() returns the entire set, and getControl sample code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) 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() sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.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 sample code for javax.sound.sampled.SourceDataLine.write(byte[], int, int) definition code for javax.sound.sampled.SourceDataLine.write(byte[], int, int) and TargetDataLine.read sample code for javax.sound.sampled.TargetDataLine.read(byte[], int, int) definition code for javax.sound.sampled.TargetDataLine.read(byte[], int, int) .

You can register an object to receive notifications whenever the line's state changes. The object must implement the LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener interface, which consists of the single method update sample code for javax.sound.sampled.LineListener.update(javax.sound.sampled.LineEvent) definition code for javax.sound.sampled.LineListener.update(javax.sound.sampled.LineEvent) . This method will be invoked when a line opens and closes (and, if it's a DataLine sample code for javax.sound.sampled.DataLine definition code for javax.sound.sampled.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.

Since:
1.3
See Also:
LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

Nested Class Summary
static class Line.Info sample code for javax.sound.sampled.Line.Info definition code for javax.sound.sampled.Line.Info
          A Line.Info object contains information about a line.
 
Method Summary
 void addLineListener sample code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) (LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener  listener)
          Adds a listener to this line.
 void close sample code for javax.sound.sampled.Line.close() definition code for javax.sound.sampled.Line.close() ()
          Closes the line, indicating that any system resources in use by the line can be released.
 Control sample code for javax.sound.sampled.Control definition code for javax.sound.sampled.Control getControl sample code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) (Control.Type sample code for javax.sound.sampled.Control.Type definition code for javax.sound.sampled.Control.Type  control)
          Obtains a control of the specified type, if there is any.
 Control sample code for javax.sound.sampled.Control definition code for javax.sound.sampled.Control [] getControls sample code for javax.sound.sampled.Line.getControls() definition code for javax.sound.sampled.Line.getControls() ()
          Obtains the set of controls associated with this line.
 Line.Info sample code for javax.sound.sampled.Line.Info definition code for javax.sound.sampled.Line.Info getLineInfo sample code for javax.sound.sampled.Line.getLineInfo() definition code for javax.sound.sampled.Line.getLineInfo() ()
          Obtains the Line.Info object describing this line.
 boolean isControlSupported sample code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) (Control.Type sample code for javax.sound.sampled.Control.Type definition code for javax.sound.sampled.Control.Type  control)
          Indicates whether the line supports a control of the specified type.
 boolean isOpen sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.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 sample code for javax.sound.sampled.Line.open() definition code for javax.sound.sampled.Line.open() ()
          Opens the line, indicating that it should acquire any required system resources and become operational.
 void removeLineListener sample code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) (LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener  listener)
          Removes the specified listener from this line's list of listeners.
 

Method Detail

getLineInfo sample code for javax.sound.sampled.Line.getLineInfo() definition code for javax.sound.sampled.Line.getLineInfo()

Line.Info sample code for javax.sound.sampled.Line.Info definition code for javax.sound.sampled.Line.Info  getLineInfo()
Obtains the Line.Info object describing this line.

Returns:
description of the line

open sample code for javax.sound.sampled.Line.open() definition code for javax.sound.sampled.Line.open()

void open()
          throws LineUnavailableException sample code for javax.sound.sampled.LineUnavailableException definition code for javax.sound.sampled.LineUnavailableException 
Opens the line, indicating that it should acquire any required system resources and become operational. If this operation succeeds, the line is marked as open, and an 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 sample code for javax.sound.sampled.SourceDataLine definition code for javax.sound.sampled.SourceDataLine and TargetDataLine sample code for javax.sound.sampled.TargetDataLine definition code for javax.sound.sampled.TargetDataLine objects, this means that the line is opened with default settings. For a Clip sample code for javax.sound.sampled.Clip definition code for javax.sound.sampled.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.

Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if this method is called on a Clip instance.
LineUnavailableException sample code for javax.sound.sampled.LineUnavailableException definition code for javax.sound.sampled.LineUnavailableException - if the line cannot be opened due to resource restrictions.
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if the line cannot be opened due to security restrictions.
See Also:
close() sample code for javax.sound.sampled.Line.close() definition code for javax.sound.sampled.Line.close() , isOpen() sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.isOpen() , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent , DataLine sample code for javax.sound.sampled.DataLine definition code for javax.sound.sampled.DataLine , Clip.open(AudioFormat, byte[], int, int) sample code for javax.sound.sampled.Clip.open(javax.sound.sampled.AudioFormat, byte[], int, int) definition code for javax.sound.sampled.Clip.open(javax.sound.sampled.AudioFormat, byte[], int, int) , Clip.open(AudioInputStream) sample code for javax.sound.sampled.Clip.open(javax.sound.sampled.AudioInputStream) definition code for javax.sound.sampled.Clip.open(javax.sound.sampled.AudioInputStream)

close sample code for javax.sound.sampled.Line.close() definition code for javax.sound.sampled.Line.close()

void close()
Closes the line, indicating that any system resources in use by the line can be released. If this operation succeeds, the line is marked closed and a CLOSE event is dispatched to the line's listeners.

Throws:
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - if the line cannot be closed due to security restrictions.
See Also:
open() sample code for javax.sound.sampled.Line.open() definition code for javax.sound.sampled.Line.open() , isOpen() sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.isOpen() , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

isOpen sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.isOpen()

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.

Returns:
true if the line is open, otherwise false
See Also:
open() sample code for javax.sound.sampled.Line.open() definition code for javax.sound.sampled.Line.open() , close() sample code for javax.sound.sampled.Line.close() definition code for javax.sound.sampled.Line.close()

getControls sample code for javax.sound.sampled.Line.getControls() definition code for javax.sound.sampled.Line.getControls()

Control sample code for javax.sound.sampled.Control definition code for javax.sound.sampled.Control [] getControls()
Obtains the set of controls associated with this line. Some controls may only be available when the line is open. If there are no controls, this method returns an array of length 0.

Returns:
the array of controls
See Also:
getControl(javax.sound.sampled.Control.Type) sample code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type)

isControlSupported sample code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type)

boolean isControlSupported(Control.Type sample code for javax.sound.sampled.Control.Type definition code for javax.sound.sampled.Control.Type  control)
Indicates whether the line supports a control of the specified type. Some controls may only be available when the line is open.

Parameters:
control - the type of the control for which support is queried
Returns:
true if at least one control of the specified type is supported, otherwise false.

getControl sample code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type)

Control sample code for javax.sound.sampled.Control definition code for javax.sound.sampled.Control  getControl(Control.Type sample code for javax.sound.sampled.Control.Type definition code for javax.sound.sampled.Control.Type  control)
Obtains a control of the specified type, if there is any. Some controls may only be available when the line is open.

Parameters:
control - the type of the requested control
Returns:
a control of the specified type
Throws:
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if a control of the specified type is not supported
See Also:
getControls() sample code for javax.sound.sampled.Line.getControls() definition code for javax.sound.sampled.Line.getControls() , isControlSupported(Control.Type control) sample code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type)

addLineListener sample code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener)

void addLineListener(LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener  listener)
Adds a listener to this line. Whenever the line's status changes, the listener's update() method is called with a LineEvent object that describes the change.

Parameters:
listener - the object to add as a listener to this line
See Also:
removeLineListener(javax.sound.sampled.LineListener) sample code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) , LineListener.update(javax.sound.sampled.LineEvent) sample code for javax.sound.sampled.LineListener.update(javax.sound.sampled.LineEvent) definition code for javax.sound.sampled.LineListener.update(javax.sound.sampled.LineEvent) , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

removeLineListener sample code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener)

void removeLineListener(LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener  listener)
Removes the specified listener from this line's list of listeners.

Parameters:
listener - listener to remove
See Also:
addLineListener(javax.sound.sampled.LineListener) sample code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener)