3261N/A * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The <code>Line</code> interface represents a mono or multi-channel 0N/A * audio feed. A line is an element of the digital audio 0N/A * "pipeline," such as a mixer, an input or output port, 0N/A * or a data path into or out of a mixer. 0N/A * A line can have controls, such as gain, pan, and reverb. 0N/A * The controls themselves are instances of classes that extend the 0N/A * base <code>{@link Control}</code> class. 0N/A * The <code>Line</code> interface provides two accessor methods for 0N/A * obtaining the line's controls: <code>{@link #getControls getControls}</code> returns the 0N/A * entire set, and <code>{@link #getControl getControl}</code> returns a single control of 0N/A * Lines exist in various states at different times. When a line opens, it reserves system 0N/A * resources for itself, and when it closes, these resources are freed for 0N/A * other objects or applications. The <code>{@link #isOpen()}</code> method lets 0N/A * you discover whether a line is open or closed. 0N/A * An open line need not be processing data, however. Such processing is 0N/A * typically initiated by subinterface methods such as 0N/A * <code>{@link SourceDataLine#write SourceDataLine.write}</code> and 0N/A * <code>{@link TargetDataLine#read TargetDataLine.read}</code>. 0N/A * You can register an object to receive notifications whenever the line's 0N/A * state changes. The object must implement the <code>{@link LineListener}</code> 0N/A * interface, which consists of the single method 0N/A * <code>{@link LineListener#update update}</code>. 0N/A * This method will be invoked when a line opens and closes (and, if it's a 0N/A * {@link DataLine}, when it starts and stops). 0N/A * An object can be registered to listen to multiple lines. The event it 0N/A * receives in its <code>update</code> method will specify which line created 0N/A * the event, what type of event it was 0N/A * (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>), 0N/A * and how many sample frames the line had processed at the time the event occurred. 0N/A * Certain line operations, such as open and close, can generate security 0N/A * exceptions if invoked by unprivileged code when the line is a shared audio 0N/A * @author Kara Kytle 0N/A * Obtains the <code>Line.Info</code> object describing this 0N/A * @return description of the line 0N/A * Opens the line, indicating that it should acquire any required 0N/A * system resources and become operational. 0N/A * succeeds, the line is marked as open, and an <code>OPEN</code> event is dispatched 0N/A * to the line's listeners. 0N/A * Note that some lines, once closed, cannot be reopened. Attempts 0N/A * to reopen such a line will always result in an <code>LineUnavailableException</code>. 0N/A * Some types of lines have configurable properties that may affect 0N/A * resource allocation. For example, a <code>DataLine</code> must 0N/A * be opened with a particular format and buffer size. Such lines 0N/A * should provide a mechanism for configuring these properties, such 0N/A * as an additional <code>open</code> method or methods which allow 0N/A * an application to specify the desired settings. 0N/A * This method takes no arguments, and opens the line with the current 0N/A * settings. For <code>{@link SourceDataLine}</code> and 0N/A * <code>{@link TargetDataLine}</code> objects, this means that the line is 0N/A * opened with default settings. For a <code>{@link Clip}</code>, however, 0N/A * the buffer size is determined when data is loaded. Since this method does not 0N/A * allow the application to specify any data to load, an IllegalArgumentException 0N/A * is thrown. Therefore, you should instead use one of the <code>open</code> methods 0N/A * provided in the <code>Clip</code> interface to load data into the <code>Clip</code>. 0N/A * For <code>DataLine</code>'s, if the <code>DataLine.Info</code> 0N/A * object which was used to retrieve the line, specifies at least 0N/A * one fully qualified audio format, the last one will be used 0N/A * as the default format. 0N/A * @throws IllegalArgumentException if this method is called on a Clip instance. 0N/A * @throws LineUnavailableException if the line cannot be 0N/A * opened due to resource restrictions. 0N/A * @throws SecurityException if the line cannot be 0N/A * opened due to security restrictions. 0N/A * @see Clip#open(AudioFormat, byte[], int, int) 0N/A * @see Clip#open(AudioInputStream) 0N/A * Closes the line, indicating that any system resources 0N/A * in use by the line can be released. If this operation 0N/A * succeeds, the line is marked closed and a <code>CLOSE</code> event is dispatched 0N/A * to the line's listeners. 0N/A * @throws SecurityException if the line cannot be 0N/A * closed due to security restrictions. 0N/A * Indicates whether the line is open, meaning that it has reserved 0N/A * system resources and is operational, although it might not currently be 0N/A * playing or capturing sound. 0N/A * @return <code>true</code> if the line is open, otherwise <code>false</code> 0N/A * Obtains the set of controls associated with this line. 0N/A * Some controls may only be available when the line is open. 0N/A * If there are no controls, this method returns an array of length 0. 0N/A * @return the array of controls 0N/A * Indicates whether the line supports a control of the specified type. 0N/A * Some controls may only be available when the line is open. 0N/A * @param control the type of the control for which support is queried 0N/A * @return <code>true</code> if at least one control of the specified type is 0N/A * supported, otherwise <code>false</code>. 0N/A * Obtains a control of the specified type, 0N/A * Some controls may only be available when the line is open. 0N/A * @param control the type of the requested control 0N/A * @return a control of the specified type 0N/A * @throws IllegalArgumentException if a control of the specified type 0N/A * @see #isControlSupported(Control.Type control) 0N/A * Adds a listener to this line. Whenever the line's status changes, the 0N/A * listener's <code>update()</code> method is called with a <code>LineEvent</code> object 0N/A * that describes the change. 0N/A * @param listener the object to add as a listener to this line 0N/A * @see #removeLineListener 0N/A * @see LineListener#update 0N/A * Removes the specified listener from this line's list of listeners. 0N/A * @param listener listener to remove 0N/A * @see #addLineListener 0N/A * A <code>Line.Info</code> object contains information about a line. 0N/A * The only information provided by <code>Line.Info</code> itself 0N/A * is the Java class of the line. 0N/A * A subclass of <code>Line.Info</code> adds other kinds of information 0N/A * about the line. This additional information depends on which <code>Line</code> 0N/A * subinterface is implemented by the kind of line that the <code>Line.Info</code> 0N/A * subclass describes. 0N/A * A <code>Line.Info</code> can be retrieved using various methods of 0N/A * the <code>Line</code>, <code>Mixer</code>, and <code>AudioSystem</code> 0N/A * interfaces. Other such methods let you pass a <code>Line.Info</code> as 0N/A * an argument, to learn whether lines matching the specified configuration 0N/A * are available and to obtain them. 0N/A * @author Kara Kytle 0N/A * @see Line#getLineInfo 0N/A * @see Mixer#getSourceLineInfo 0N/A * @see Mixer#getTargetLineInfo 0N/A * @see Mixer#getLine <code>Mixer.getLine(Line.Info)</code> 0N/A * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getSourceLineInfo(Line.Info)</code> 0N/A * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getTargetLineInfo(Line.Info)</code> 0N/A * @see Mixer#isLineSupported <code>Mixer.isLineSupported(Line.Info)</code> 0N/A * @see AudioSystem#getLine <code>AudioSystem.getLine(Line.Info)</code> 0N/A * @see AudioSystem#getSourceLineInfo <code>AudioSystem.getSourceLineInfo(Line.Info)</code> 0N/A * @see AudioSystem#getTargetLineInfo <code>AudioSystem.getTargetLineInfo(Line.Info)</code> 0N/A * @see AudioSystem#isLineSupported <code>AudioSystem.isLineSupported(Line.Info)</code> 0N/A * The class of the line described by the info object. 0N/A * Constructs an info object that describes a line of the specified class. 0N/A * This constructor is typically used by an application to 0N/A * describe a desired line. 0N/A * @param lineClass the class of the line that the new Line.Info object describes 0N/A * Obtains the class of the line that this Line.Info object describes. 0N/A * @return the described line's class 0N/A * Indicates whether the specified info object matches this one. 0N/A * To match, the specified object must be identical to or 0N/A * a special case of this one. The specified info object 0N/A * must be either an instance of the same class as this one, 0N/A * or an instance of a sub-type of this one. In addition, the 0N/A * attributes of the specified object must be compatible with the 0N/A * capabilities of this one. Specifically, the routing configuration 0N/A * for the specified info object must be compatible with that of this 0N/A * Subclasses may add other criteria to determine whether the two objects 0N/A * @param info the info object which is being compared to this one 0N/A * @return <code>true</code> if the specified object matches this one, 0N/A * <code>false</code> otherwise 0N/A // $$kk: 08.30.99: is this backwards? 0N/A // dataLine.matches(targetDataLine) == true: targetDataLine is always dataLine 0N/A // targetDataLine.matches(dataLine) == false 0N/A // so if i want to make sure i get a targetDataLine, i need: 0N/A // targetDataLine.matches(prospective_match) == true 0N/A // => prospective_match may be other things as well, but it is at least a targetDataLine 0N/A // targetDataLine defines the requirements which prospective_match must meet. 0N/A // "if this Class object represents a declared class, this method returns 0N/A // true if the specified Object argument is an instance of the represented 0N/A // class (or of any of its subclasses)" 0N/A // GainControlClass.isInstance(MyGainObj) => true 0N/A // GainControlClass.isInstance(MySpecialGainInterfaceObj) => true 0N/A // this_class.isInstance(that_object) => that object can by cast to this class 0N/A // => that_object's class may be a subtype of this_class 0N/A // => that may be more specific (subtype) of this 0N/A // "If this Class object represents an interface, this method returns true 0N/A // if the class or any superclass of the specified Object argument implements 0N/A // GainControlClass.isInstance(MyGainObj) => true 0N/A // GainControlClass.isInstance(GenericControlObj) => may be false 0N/A // => that may be more specific 0N/A // this.isAssignableFrom(that) => this is same or super to that 0N/A // => this is at least as general as that 0N/A // => that may be subtype of this 0N/A * Obtains a textual description of the line info. 0N/A * @return a string description