/*
* Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sound.sampled;
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 ControlLine interface provides two accessor methods for
obtaining the line's controls: getControlsgetControl
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()SourceDataLine.writeTargetDataLine.read
You can register an object to receive notifications whenever the line's
state changes. The object must implement the LineListenerupdateDataLine, 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.
Author: Kara Kytle See Also: Since: 1.3
/**
* The <code>Line</code> 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.
* <p>
* A line can have controls, such as gain, pan, and reverb.
* The controls themselves are instances of classes that extend the
* base <code>{@link Control}</code> class.
* The <code>Line</code> interface provides two accessor methods for
* obtaining the line's controls: <code>{@link #getControls getControls}</code> returns the
* entire set, and <code>{@link #getControl getControl}</code> returns a single control of
* specified type.
* <p>
* 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 <code>{@link #isOpen()}</code> 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
* <code>{@link SourceDataLine#write SourceDataLine.write}</code> and
* <code>{@link TargetDataLine#read TargetDataLine.read}</code>.
*<p>
* You can register an object to receive notifications whenever the line's
* state changes. The object must implement the <code>{@link LineListener}</code>
* interface, which consists of the single method
* <code>{@link LineListener#update update}</code>.
* This method will be invoked when a line opens and closes (and, if it's a
* {@link DataLine}, when it starts and stops).
*<p>
* An object can be registered to listen to multiple lines. The event it
* receives in its <code>update</code> method will specify which line created
* the event, what type of event it was
* (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>),
* and how many sample frames the line had processed at the time the event occurred.
* <p>
* 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.
*
* @author Kara Kytle
*
* @see LineEvent
* @since 1.3
*/
public interface Line {
Obtains the Line.Info object describing this
line.
Returns: description of the line
/**
* Obtains the <code>Line.Info</code> object describing this
* line.
* @return description of the line
*/
public Line.Info getLineInfo();
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 SourceDataLineTargetDataLineClipopen 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 – if this method is called on a Clip instance.
- LineUnavailableException – if the line cannot be
opened due to resource restrictions.
- SecurityException – if the line cannot be
opened due to security restrictions.
See Also:
/**
* 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 <code>OPEN</code> event is dispatched
* to the line's listeners.
* <p>
* Note that some lines, once closed, cannot be reopened. Attempts
* to reopen such a line will always result in an <code>LineUnavailableException</code>.
* <p>
* Some types of lines have configurable properties that may affect
* resource allocation. For example, a <code>DataLine</code> must
* be opened with a particular format and buffer size. Such lines
* should provide a mechanism for configuring these properties, such
* as an additional <code>open</code> method or methods which allow
* an application to specify the desired settings.
* <p>
* This method takes no arguments, and opens the line with the current
* settings. For <code>{@link SourceDataLine}</code> and
* <code>{@link TargetDataLine}</code> objects, this means that the line is
* opened with default settings. For a <code>{@link Clip}</code>, 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 <code>open</code> methods
* provided in the <code>Clip</code> interface to load data into the <code>Clip</code>.
* <p>
* For <code>DataLine</code>'s, if the <code>DataLine.Info</code>
* 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 if this method is called on a Clip instance.
* @throws LineUnavailableException if the line cannot be
* opened due to resource restrictions.
* @throws SecurityException if the line cannot be
* opened due to security restrictions.
*
* @see #close
* @see #isOpen
* @see LineEvent
* @see DataLine
* @see Clip#open(AudioFormat, byte[], int, int)
* @see Clip#open(AudioInputStream)
*/
public void open() throws LineUnavailableException;
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 – if the line cannot be
closed due to security restrictions.
See Also:
/**
* 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 <code>CLOSE</code> event is dispatched
* to the line's listeners.
* @throws SecurityException if the line cannot be
* closed due to security restrictions.
*
* @see #open
* @see #isOpen
* @see LineEvent
*/
public void close();
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.
See Also: Returns: true if the line is open, otherwise false
/**
* 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.
* @return <code>true</code> if the line is open, otherwise <code>false</code>
*
* @see #open()
* @see #close()
*/
public boolean isOpen();
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.
See Also: Returns: the array of controls
/**
* 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.
* @return the array of controls
* @see #getControl
*/
public Control[] getControls();
Indicates whether the line supports a control of the specified type.
Some controls may only be available when the line is open.
Params: - 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.
/**
* Indicates whether the line supports a control of the specified type.
* Some controls may only be available when the line is open.
* @param control the type of the control for which support is queried
* @return <code>true</code> if at least one control of the specified type is
* supported, otherwise <code>false</code>.
*/
public boolean isControlSupported(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.
Params: - control – the type of the requested control
Throws: - IllegalArgumentException – if a control of the specified type
is not supported
See Also: Returns: a control of the specified type
/**
* Obtains a control of the specified type,
* if there is any.
* Some controls may only be available when the line is open.
* @param control the type of the requested control
* @return a control of the specified type
* @throws IllegalArgumentException if a control of the specified type
* is not supported
* @see #getControls
* @see #isControlSupported(Control.Type control)
*/
public Control getControl(Control.Type control);
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.
Params: - listener – the object to add as a listener to this line
See Also:
/**
* Adds a listener to this line. Whenever the line's status changes, the
* listener's <code>update()</code> method is called with a <code>LineEvent</code> object
* that describes the change.
* @param listener the object to add as a listener to this line
* @see #removeLineListener
* @see LineListener#update
* @see LineEvent
*/
public void addLineListener(LineListener listener);
Removes the specified listener from this line's list of listeners.
Params: - listener – listener to remove
See Also:
/**
* Removes the specified listener from this line's list of listeners.
* @param listener listener to remove
* @see #addLineListener
*/
public void removeLineListener(LineListener listener);
A Line.Info object contains information about a line.
The only information provided by Line.Info itself
is the Java class of the line.
A subclass of Line.Info adds other kinds of information
about the line. This additional information depends on which Line
subinterface is implemented by the kind of line that the Line.Info
subclass describes.
A Line.Info can be retrieved using various methods of
the Line, Mixer, and AudioSystem
interfaces. Other such methods let you pass a Line.Info as
an argument, to learn whether lines matching the specified configuration
are available and to obtain them.
/**
* A <code>Line.Info</code> object contains information about a line.
* The only information provided by <code>Line.Info</code> itself
* is the Java class of the line.
* A subclass of <code>Line.Info</code> adds other kinds of information
* about the line. This additional information depends on which <code>Line</code>
* subinterface is implemented by the kind of line that the <code>Line.Info</code>
* subclass describes.
* <p>
* A <code>Line.Info</code> can be retrieved using various methods of
* the <code>Line</code>, <code>Mixer</code>, and <code>AudioSystem</code>
* interfaces. Other such methods let you pass a <code>Line.Info</code> as
* an argument, to learn whether lines matching the specified configuration
* are available and to obtain them.
*
* @author Kara Kytle
*
* @see Line#getLineInfo
* @see Mixer#getSourceLineInfo
* @see Mixer#getTargetLineInfo
* @see Mixer#getLine <code>Mixer.getLine(Line.Info)</code>
* @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getSourceLineInfo(Line.Info)</code>
* @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getTargetLineInfo(Line.Info)</code>
* @see Mixer#isLineSupported <code>Mixer.isLineSupported(Line.Info)</code>
* @see AudioSystem#getLine <code>AudioSystem.getLine(Line.Info)</code>
* @see AudioSystem#getSourceLineInfo <code>AudioSystem.getSourceLineInfo(Line.Info)</code>
* @see AudioSystem#getTargetLineInfo <code>AudioSystem.getTargetLineInfo(Line.Info)</code>
* @see AudioSystem#isLineSupported <code>AudioSystem.isLineSupported(Line.Info)</code>
* @since 1.3
*/
public static class Info {
The class of the line described by the info object.
/**
* The class of the line described by the info object.
*/
private final Class lineClass;
Constructs an info object that describes a line of the specified class.
This constructor is typically used by an application to
describe a desired line.
Params: - lineClass – the class of the line that the new Line.Info object describes
/**
* Constructs an info object that describes a line of the specified class.
* This constructor is typically used by an application to
* describe a desired line.
* @param lineClass the class of the line that the new Line.Info object describes
*/
public Info(Class<?> lineClass) {
if (lineClass == null) {
this.lineClass = Line.class;
} else {
this.lineClass = lineClass;
}
}
Obtains the class of the line that this Line.Info object describes.
Returns: the described line's class
/**
* Obtains the class of the line that this Line.Info object describes.
* @return the described line's class
*/
public Class<?> getLineClass() {
return lineClass;
}
Indicates whether the specified info object matches this one.
To match, the specified object must be identical to or
a special case of this one. The specified info object
must be either an instance of the same class as this one,
or an instance of a sub-type of this one. In addition, the
attributes of the specified object must be compatible with the
capabilities of this one. Specifically, the routing configuration
for the specified info object must be compatible with that of this
one.
Subclasses may add other criteria to determine whether the two objects
match.
Params: - info – the info object which is being compared to this one
Returns: true if the specified object matches this one,
false otherwise
/**
* Indicates whether the specified info object matches this one.
* To match, the specified object must be identical to or
* a special case of this one. The specified info object
* must be either an instance of the same class as this one,
* or an instance of a sub-type of this one. In addition, the
* attributes of the specified object must be compatible with the
* capabilities of this one. Specifically, the routing configuration
* for the specified info object must be compatible with that of this
* one.
* Subclasses may add other criteria to determine whether the two objects
* match.
*
* @param info the info object which is being compared to this one
* @return <code>true</code> if the specified object matches this one,
* <code>false</code> otherwise
*/
public boolean matches(Info info) {
// $$kk: 08.30.99: is this backwards?
// dataLine.matches(targetDataLine) == true: targetDataLine is always dataLine
// targetDataLine.matches(dataLine) == false
// so if i want to make sure i get a targetDataLine, i need:
// targetDataLine.matches(prospective_match) == true
// => prospective_match may be other things as well, but it is at least a targetDataLine
// targetDataLine defines the requirements which prospective_match must meet.
// "if this Class object represents a declared class, this method returns
// true if the specified Object argument is an instance of the represented
// class (or of any of its subclasses)"
// GainControlClass.isInstance(MyGainObj) => true
// GainControlClass.isInstance(MySpecialGainInterfaceObj) => true
// this_class.isInstance(that_object) => that object can by cast to this class
// => that_object's class may be a subtype of this_class
// => that may be more specific (subtype) of this
// "If this Class object represents an interface, this method returns true
// if the class or any superclass of the specified Object argument implements
// this interface"
// GainControlClass.isInstance(MyGainObj) => true
// GainControlClass.isInstance(GenericControlObj) => may be false
// => that may be more specific
if (! (this.getClass().isInstance(info)) ) {
return false;
}
// this.isAssignableFrom(that) => this is same or super to that
// => this is at least as general as that
// => that may be subtype of this
if (! (getLineClass().isAssignableFrom(info.getLineClass())) ) {
return false;
}
return true;
}
Obtains a textual description of the line info.
Returns: a string description
/**
* Obtains a textual description of the line info.
* @return a string description
*/
public String toString() {
String fullPackagePath = "javax.sound.sampled.";
String initialString = new String(getLineClass().toString());
String finalString;
int index = initialString.indexOf(fullPackagePath);
if (index != -1) {
finalString = initialString.substring(0, index) + initialString.substring( (index + fullPackagePath.length()), initialString.length() );
} else {
finalString = initialString;
}
return finalString;
}
} // class Info
} // interface Line