Back to index...

	/*
	* Copyright (c) 1999, 2010, 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 <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 extends AutoCloseable {

	/**
	* 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 <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 <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.
	* @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.
	* @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.
	* @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.
	* @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 <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.
	* @param listener listener to remove
	* @see #addLineListener
	*/
	public void removeLineListener(LineListener listener);


	/**
	* 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.
	*/
	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.
	* @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.
	* @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.
	*
	* @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.
	* @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

Back to index...