Line


1   /*
2    * @(#)Line.java    1.29 04/07/14
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.sampled;
9   
10  /**
11   * The <code>Line</code> interface represents a mono or multi-channel
12   * audio feed. A line is an element of the digital audio
13   * "pipeline," such as a mixer, an input or output port,
14   * or a data path into or out of a mixer.
15   * <p>
16   * A line can have controls, such as gain, pan, and reverb.
17   * The controls themselves are instances of classes that extend the
18   * base <code>{@link Control}</code> class.
19   * The <code>Line</code> interface provides two accessor methods for
20   * obtaining the line's controls: <code>{@link #getControls getControls}</code> returns the
21   * entire set, and <code>{@link #getControl getControl}</code> returns a single control of
22   * specified type.
23   * <p>
24   * Lines exist in various states at different times.  When a line opens, it reserves system
25   * resources for itself, and when it closes, these resources are freed for
26   * other objects or applications. The <code>{@link #isOpen()}</code> method lets
27   * you discover whether a line is open or closed.
28   * An open line need not be processing data, however.  Such processing is
29   * typically initiated by subinterface methods such as
30   * <code>{@link SourceDataLine#write SourceDataLine.write}</code> and
31   * <code>{@link TargetDataLine#read TargetDataLine.read}</code>.
32   *<p>
33   * You can register an object to receive notifications whenever the line's
34   * state changes.  The object must implement the <code>{@link LineListener}</code>
35   * interface, which consists of the single method
36   * <code>{@link LineListener#update update}</code>.
37   * This method will be invoked when a line opens and closes (and, if it's a
38   * {@link DataLine}, when it starts and stops).
39   *<p>
40   * An object can be registered to listen to multiple lines.  The event it
41   * receives in its <code>update</code> method will specify which line created
42   * the event, what type of event it was
43   * (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>),
44   * and how many sample frames the line had processed at the time the event occurred.
45   * <p>
46   * Certain line operations, such as open and close, can generate security
47   * exceptions if invoked by unprivileged code when the line is a shared audio
48   * resource.
49   *
50   * @author Kara Kytle
51   * @version 1.29, 04/07/14
52   *
53   * @see LineEvent
54   * @since 1.3
55   */
56  public interface Line {
57  
58      /**
59       * Obtains the <code>Line.Info</code> object describing this
60       * line.
61       * @return description of the line
62       */
63      public Line.Info   getLineInfo();
64  
65      /**
66       * Opens the line, indicating that it should acquire any required
67       * system resources and become operational.
68       * If this operation
69       * succeeds, the line is marked as open, and an <code>OPEN</code> event is dispatched
70       * to the line's listeners.
71       * <p>
72       * Note that some lines, once closed, cannot be reopened.  Attempts
73       * to reopen such a line will always result in an <code>LineUnavailableException</code>.
74       * <p>
75       * Some types of lines have configurable properties that may affect
76       * resource allocation.   For example, a <code>DataLine</code> must
77       * be opened with a particular format and buffer size.  Such lines
78       * should provide a mechanism for configuring these properties, such
79       * as an additional <code>open</code> method or methods which allow
80       * an application to specify the desired settings.
81       * <p>
82       * This method takes no arguments, and opens the line with the current
83       * settings.  For <code>{@link SourceDataLine}</code> and
84       * <code>{@link TargetDataLine}</code> objects, this means that the line is
85       * opened with default settings.  For a <code>{@link Clip}</code>, however,
86       * the buffer size is determined when data is loaded.  Since this method does not
87       * allow the application to specify any data to load, an IllegalArgumentException
88       * is thrown. Therefore, you should instead use one of the <code>open</code> methods
89       * provided in the <code>Clip</code> interface to load data into the <code>Clip</code>.
90       * <p>
91       * For <code>DataLine</code>'s, if the <code>DataLine.Info</code>
92       * object which was used to retrieve the line, specifies at least
93       * one fully qualified audio format, the last one will be used
94       * as the default format.
95       *
96       * @throws IllegalArgumentException if this method is called on a Clip instance.
97       * @throws LineUnavailableException if the line cannot be
98       * opened due to resource restrictions.
99       * @throws SecurityException if the line cannot be
100      * opened due to security restrictions.
101      *
102      * @see #close
103      * @see #isOpen
104      * @see LineEvent
105      * @see DataLine
106      * @see Clip#open(AudioFormat, byte[], int, int)
107      * @see Clip#open(AudioInputStream)
108      */
109     public void open() throws LineUnavailableException  ;
110 
111 
112     /**
113      * Closes the line, indicating that any system resources
114      * in use by the line can be released.  If this operation
115      * succeeds, the line is marked closed and a <code>CLOSE</code> event is dispatched
116      * to the line's listeners.
117      * @throws SecurityException if the line cannot be
118      * closed due to security restrictions.
119      *
120      * @see #open
121      * @see #isOpen
122      * @see LineEvent
123      */
124     public void close();
125 
126 
127 
128     /**
129      * Indicates whether the line is open, meaning that it has reserved
130      * system resources and is operational, although it might not currently be
131      * playing or capturing sound.
132      * @return <code>true</code> if the line is open, otherwise <code>false</code>
133      *
134      * @see #open()
135      * @see #close()
136      */
137     public boolean isOpen();
138 
139 
140     /**
141      * Obtains the set of controls associated with this line.
142      * Some controls may only be available when the line is open.
143      * If there are no controls, this method returns an array of length 0.
144      * @return the array of controls
145      * @see #getControl
146      */
147     public Control  [] getControls();
148 
149     /**
150      * Indicates whether the line supports a control of the specified type.
151      * Some controls may only be available when the line is open.
152      * @param control the type of the control for which support is queried
153      * @return <code>true</code> if at least one control of the specified type is
154      * supported, otherwise <code>false</code>.
155      */
156     public boolean isControlSupported(Control.Type   control);
157 
158 
159     /**
160      * Obtains a control of the specified type,
161      * if there is any.
162      * Some controls may only be available when the line is open.
163      * @param control the type of the requested control
164      * @return a control of the specified type
165      * @throws IllegalArgumentException if a control of the specified type
166      * is not supported
167      * @see #getControls
168      * @see #isControlSupported(Control.Type control)
169      */
170     public Control   getControl(Control.Type   control);
171 
172 
173     /**
174      * Adds a listener to this line.  Whenever the line's status changes, the
175      * listener's <code>update()</code> method is called with a <code>LineEvent</code> object
176      * that describes the change.
177      * @param listener the object to add as a listener to this line
178      * @see #removeLineListener
179      * @see LineListener#update
180      * @see LineEvent
181      */
182     public void addLineListener(LineListener   listener);
183 
184 
185     /**
186      * Removes the specified listener from this line's list of listeners.
187      * @param listener listener to remove
188      * @see #addLineListener
189      */
190     public void removeLineListener(LineListener   listener);
191 
192 
193     /**
194      * A <code>Line.Info</code> object contains information about a line.
195      * The only information provided by <code>Line.Info</code> itself
196      * is the Java class of the line.
197      * A subclass of <code>Line.Info</code> adds other kinds of information
198      * about the line.  This additional information depends on which <code>Line</code>
199      * subinterface is implemented by the kind of line that the <code>Line.Info</code>
200      * subclass describes.
201      * <p>
202      * A <code>Line.Info</code> can be retrieved using various methods of
203      * the <code>Line</code>, <code>Mixer</code>, and <code>AudioSystem</code>
204      * interfaces.  Other such methods let you pass a <code>Line.Info</code> as
205      * an argument, to learn whether lines matching the specified configuration
206      * are available and to obtain them.
207      *
208      * @author Kara Kytle
209      * @version 1.29, 04/07/14
210      *
211      * @see Line#getLineInfo
212      * @see Mixer#getSourceLineInfo
213      * @see Mixer#getTargetLineInfo
214      * @see Mixer#getLine <code>Mixer.getLine(Line.Info)</code>
215      * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getSourceLineInfo(Line.Info)</code>
216      * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getTargetLineInfo(Line.Info)</code>
217      * @see Mixer#isLineSupported <code>Mixer.isLineSupported(Line.Info)</code>
218      * @see AudioSystem#getLine <code>AudioSystem.getLine(Line.Info)</code>
219      * @see AudioSystem#getSourceLineInfo <code>AudioSystem.getSourceLineInfo(Line.Info)</code>
220      * @see AudioSystem#getTargetLineInfo <code>AudioSystem.getTargetLineInfo(Line.Info)</code>
221      * @see AudioSystem#isLineSupported <code>AudioSystem.isLineSupported(Line.Info)</code>
222      * @since 1.3
223      */
224     public static class Info {
225 
226     /**
227      * The class of the line described by the info object.
228      */
229     private final Class   lineClass;
230 
231 
232     /**
233      * Constructs an info object that describes a line of the specified class.
234      * This constructor is typically used by an application to
235      * describe a desired line.
236      * @param lineClass the class of the line that the new Line.Info object describes
237      */
238     public Info(Class  <?> lineClass) {
239 
240         if (lineClass == null) {
241         this.lineClass = Line  .class;
242         } else {
243         this.lineClass = lineClass;
244         }
245     }
246 
247 
248 
249     /**
250      * Obtains the class of the line that this Line.Info object describes.
251      * @return the described line's class
252      */
253     public Class  <?> getLineClass() {
254         return lineClass;
255     }
256 
257 
258     /**
259      * Indicates whether the specified info object matches this one.
260      * To match, the specified object must be identical to or
261      * a special case of this one.  The specified info object
262      * must be either an instance of the same class as this one,
263      * or an instance of a sub-type of this one.  In addition, the
264      * attributes of the specified object must be compatible with the
265      * capabilities of this one.  Specifically, the routing configuration
266      * for the specified info object must be compatible with that of this
267      * one.
268      * Subclasses may add other criteria to determine whether the two objects
269      * match.
270      *
271      * @param info the info object which is being compared to this one
272      * @return <code>true</code> if the specified object matches this one,
273      * <code>false</code> otherwise
274      */
275     public boolean matches(Info info) {
276 
277         // $$kk: 08.30.99: is this backwards?
278         // dataLine.matches(targetDataLine) == true: targetDataLine is always dataLine
279         // targetDataLine.matches(dataLine) == false
280         // so if i want to make sure i get a targetDataLine, i need:
281         // targetDataLine.matches(prospective_match) == true
282         // => prospective_match may be other things as well, but it is at least a targetDataLine
283         // targetDataLine defines the requirements which prospective_match must meet.
284 
285 
286         // "if this Class object represents a declared class, this method returns
287         // true if the specified Object argument is an instance of the represented
288         // class (or of any of its subclasses)"
289         // GainControlClass.isInstance(MyGainObj) => true
290         // GainControlClass.isInstance(MySpecialGainInterfaceObj) => true
291 
292         // this_class.isInstance(that_object)   => that object can by cast to this class
293         //                                      => that_object's class may be a subtype of this_class
294         //                                      => that may be more specific (subtype) of this
295 
296         // "If this Class object represents an interface, this method returns true
297         // if the class or any superclass of the specified Object argument implements
298         // this interface"
299         // GainControlClass.isInstance(MyGainObj) => true
300         // GainControlClass.isInstance(GenericControlObj) => may be false
301         // => that may be more specific
302 
303         if (! (this.getClass().isInstance(info)) ) {
304         return false;
305         }
306 
307 
308         // this.isAssignableFrom(that)  =>  this is same or super to that
309         //                              =>  this is at least as general as that
310         //                              =>  that may be subtype of this
311 
312         if (! (getLineClass().isAssignableFrom(info.getLineClass())) ) {
313         return false;
314         }
315 
316         return true;
317     }
318 
319 
320     /**
321      * Obtains a textual description of the line info.
322      * @return a string description
323      */
324     public String   toString() {
325 
326         String   fullPackagePath = "javax.sound.sampled.";
327         String   initialString = new String  (getLineClass().toString());
328         String   finalString;
329 
330         int index = initialString.indexOf(fullPackagePath);
331 
332         if (index != -1) {
333         finalString = initialString.substring(0, index) + initialString.substring( (index + fullPackagePath.length()), initialString.length() );
334         } else {
335         finalString = initialString;
336         }
337 
338         return finalString;
339     }
340 
341     } // class Info
342 
343 } // interface Line
344
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags