001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 /**
029 * The <code>Line</code> interface represents a mono or multi-channel
030 * audio feed. A line is an element of the digital audio
031 * "pipeline," such as a mixer, an input or output port,
032 * or a data path into or out of a mixer.
033 * <p>
034 * A line can have controls, such as gain, pan, and reverb.
035 * The controls themselves are instances of classes that extend the
036 * base <code>{@link Control}</code> class.
037 * The <code>Line</code> interface provides two accessor methods for
038 * obtaining the line's controls: <code>{@link #getControls getControls}</code> returns the
039 * entire set, and <code>{@link #getControl getControl}</code> returns a single control of
040 * specified type.
041 * <p>
042 * Lines exist in various states at different times. When a line opens, it reserves system
043 * resources for itself, and when it closes, these resources are freed for
044 * other objects or applications. The <code>{@link #isOpen()}</code> method lets
045 * you discover whether a line is open or closed.
046 * An open line need not be processing data, however. Such processing is
047 * typically initiated by subinterface methods such as
048 * <code>{@link SourceDataLine#write SourceDataLine.write}</code> and
049 * <code>{@link TargetDataLine#read TargetDataLine.read}</code>.
050 *<p>
051 * You can register an object to receive notifications whenever the line's
052 * state changes. The object must implement the <code>{@link LineListener}</code>
053 * interface, which consists of the single method
054 * <code>{@link LineListener#update update}</code>.
055 * This method will be invoked when a line opens and closes (and, if it's a
056 * {@link DataLine}, when it starts and stops).
057 *<p>
058 * An object can be registered to listen to multiple lines. The event it
059 * receives in its <code>update</code> method will specify which line created
060 * the event, what type of event it was
061 * (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>),
062 * and how many sample frames the line had processed at the time the event occurred.
063 * <p>
064 * Certain line operations, such as open and close, can generate security
065 * exceptions if invoked by unprivileged code when the line is a shared audio
066 * resource.
067 *
068 * @author Kara Kytle
069 * @version 1.36, 07/05/05
070 *
071 * @see LineEvent
072 * @since 1.3
073 */
074 public interface Line {
075
076 /**
077 * Obtains the <code>Line.Info</code> object describing this
078 * line.
079 * @return description of the line
080 */
081 public Line.Info getLineInfo();
082
083 /**
084 * Opens the line, indicating that it should acquire any required
085 * system resources and become operational.
086 * If this operation
087 * succeeds, the line is marked as open, and an <code>OPEN</code> event is dispatched
088 * to the line's listeners.
089 * <p>
090 * Note that some lines, once closed, cannot be reopened. Attempts
091 * to reopen such a line will always result in an <code>LineUnavailableException</code>.
092 * <p>
093 * Some types of lines have configurable properties that may affect
094 * resource allocation. For example, a <code>DataLine</code> must
095 * be opened with a particular format and buffer size. Such lines
096 * should provide a mechanism for configuring these properties, such
097 * as an additional <code>open</code> method or methods which allow
098 * an application to specify the desired settings.
099 * <p>
100 * This method takes no arguments, and opens the line with the current
101 * settings. For <code>{@link SourceDataLine}</code> and
102 * <code>{@link TargetDataLine}</code> objects, this means that the line is
103 * opened with default settings. For a <code>{@link Clip}</code>, however,
104 * the buffer size is determined when data is loaded. Since this method does not
105 * allow the application to specify any data to load, an IllegalArgumentException
106 * is thrown. Therefore, you should instead use one of the <code>open</code> methods
107 * provided in the <code>Clip</code> interface to load data into the <code>Clip</code>.
108 * <p>
109 * For <code>DataLine</code>'s, if the <code>DataLine.Info</code>
110 * object which was used to retrieve the line, specifies at least
111 * one fully qualified audio format, the last one will be used
112 * as the default format.
113 *
114 * @throws IllegalArgumentException if this method is called on a Clip instance.
115 * @throws LineUnavailableException if the line cannot be
116 * opened due to resource restrictions.
117 * @throws SecurityException if the line cannot be
118 * opened due to security restrictions.
119 *
120 * @see #close
121 * @see #isOpen
122 * @see LineEvent
123 * @see DataLine
124 * @see Clip#open(AudioFormat, byte[], int, int)
125 * @see Clip#open(AudioInputStream)
126 */
127 public void open() throws LineUnavailableException;
128
129 /**
130 * Closes the line, indicating that any system resources
131 * in use by the line can be released. If this operation
132 * succeeds, the line is marked closed and a <code>CLOSE</code> event is dispatched
133 * to the line's listeners.
134 * @throws SecurityException if the line cannot be
135 * closed due to security restrictions.
136 *
137 * @see #open
138 * @see #isOpen
139 * @see LineEvent
140 */
141 public void close();
142
143 /**
144 * Indicates whether the line is open, meaning that it has reserved
145 * system resources and is operational, although it might not currently be
146 * playing or capturing sound.
147 * @return <code>true</code> if the line is open, otherwise <code>false</code>
148 *
149 * @see #open()
150 * @see #close()
151 */
152 public boolean isOpen();
153
154 /**
155 * Obtains the set of controls associated with this line.
156 * Some controls may only be available when the line is open.
157 * If there are no controls, this method returns an array of length 0.
158 * @return the array of controls
159 * @see #getControl
160 */
161 public Control[] getControls();
162
163 /**
164 * Indicates whether the line supports a control of the specified type.
165 * Some controls may only be available when the line is open.
166 * @param control the type of the control for which support is queried
167 * @return <code>true</code> if at least one control of the specified type is
168 * supported, otherwise <code>false</code>.
169 */
170 public boolean isControlSupported(Control.Type control);
171
172 /**
173 * Obtains a control of the specified type,
174 * if there is any.
175 * Some controls may only be available when the line is open.
176 * @param control the type of the requested control
177 * @return a control of the specified type
178 * @throws IllegalArgumentException if a control of the specified type
179 * is not supported
180 * @see #getControls
181 * @see #isControlSupported(Control.Type control)
182 */
183 public Control getControl(Control.Type control);
184
185 /**
186 * Adds a listener to this line. Whenever the line's status changes, the
187 * listener's <code>update()</code> method is called with a <code>LineEvent</code> object
188 * that describes the change.
189 * @param listener the object to add as a listener to this line
190 * @see #removeLineListener
191 * @see LineListener#update
192 * @see LineEvent
193 */
194 public void addLineListener(LineListener listener);
195
196 /**
197 * Removes the specified listener from this line's list of listeners.
198 * @param listener listener to remove
199 * @see #addLineListener
200 */
201 public void removeLineListener(LineListener listener);
202
203 /**
204 * A <code>Line.Info</code> object contains information about a line.
205 * The only information provided by <code>Line.Info</code> itself
206 * is the Java class of the line.
207 * A subclass of <code>Line.Info</code> adds other kinds of information
208 * about the line. This additional information depends on which <code>Line</code>
209 * subinterface is implemented by the kind of line that the <code>Line.Info</code>
210 * subclass describes.
211 * <p>
212 * A <code>Line.Info</code> can be retrieved using various methods of
213 * the <code>Line</code>, <code>Mixer</code>, and <code>AudioSystem</code>
214 * interfaces. Other such methods let you pass a <code>Line.Info</code> as
215 * an argument, to learn whether lines matching the specified configuration
216 * are available and to obtain them.
217 *
218 * @author Kara Kytle
219 * @version 1.36, 07/05/05
220 *
221 * @see Line#getLineInfo
222 * @see Mixer#getSourceLineInfo
223 * @see Mixer#getTargetLineInfo
224 * @see Mixer#getLine <code>Mixer.getLine(Line.Info)</code>
225 * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getSourceLineInfo(Line.Info)</code>
226 * @see Mixer#getSourceLineInfo(Line.Info) <code>Mixer.getTargetLineInfo(Line.Info)</code>
227 * @see Mixer#isLineSupported <code>Mixer.isLineSupported(Line.Info)</code>
228 * @see AudioSystem#getLine <code>AudioSystem.getLine(Line.Info)</code>
229 * @see AudioSystem#getSourceLineInfo <code>AudioSystem.getSourceLineInfo(Line.Info)</code>
230 * @see AudioSystem#getTargetLineInfo <code>AudioSystem.getTargetLineInfo(Line.Info)</code>
231 * @see AudioSystem#isLineSupported <code>AudioSystem.isLineSupported(Line.Info)</code>
232 * @since 1.3
233 */
234 public static class Info {
235
236 /**
237 * The class of the line described by the info object.
238 */
239 private final Class lineClass;
240
241 /**
242 * Constructs an info object that describes a line of the specified class.
243 * This constructor is typically used by an application to
244 * describe a desired line.
245 * @param lineClass the class of the line that the new Line.Info object describes
246 */
247 public Info(Class<?> lineClass) {
248
249 if (lineClass == null) {
250 this .lineClass = Line.class;
251 } else {
252 this .lineClass = lineClass;
253 }
254 }
255
256 /**
257 * Obtains the class of the line that this Line.Info object describes.
258 * @return the described line's class
259 */
260 public Class<?> getLineClass() {
261 return lineClass;
262 }
263
264 /**
265 * Indicates whether the specified info object matches this one.
266 * To match, the specified object must be identical to or
267 * a special case of this one. The specified info object
268 * must be either an instance of the same class as this one,
269 * or an instance of a sub-type of this one. In addition, the
270 * attributes of the specified object must be compatible with the
271 * capabilities of this one. Specifically, the routing configuration
272 * for the specified info object must be compatible with that of this
273 * one.
274 * Subclasses may add other criteria to determine whether the two objects
275 * match.
276 *
277 * @param info the info object which is being compared to this one
278 * @return <code>true</code> if the specified object matches this one,
279 * <code>false</code> otherwise
280 */
281 public boolean matches(Info info) {
282
283 // $$kk: 08.30.99: is this backwards?
284 // dataLine.matches(targetDataLine) == true: targetDataLine is always dataLine
285 // targetDataLine.matches(dataLine) == false
286 // so if i want to make sure i get a targetDataLine, i need:
287 // targetDataLine.matches(prospective_match) == true
288 // => prospective_match may be other things as well, but it is at least a targetDataLine
289 // targetDataLine defines the requirements which prospective_match must meet.
290
291 // "if this Class object represents a declared class, this method returns
292 // true if the specified Object argument is an instance of the represented
293 // class (or of any of its subclasses)"
294 // GainControlClass.isInstance(MyGainObj) => true
295 // GainControlClass.isInstance(MySpecialGainInterfaceObj) => true
296
297 // this_class.isInstance(that_object) => that object can by cast to this class
298 // => that_object's class may be a subtype of this_class
299 // => that may be more specific (subtype) of this
300
301 // "If this Class object represents an interface, this method returns true
302 // if the class or any superclass of the specified Object argument implements
303 // this interface"
304 // GainControlClass.isInstance(MyGainObj) => true
305 // GainControlClass.isInstance(GenericControlObj) => may be false
306 // => that may be more specific
307
308 if (!(this .getClass().isInstance(info))) {
309 return false;
310 }
311
312 // this.isAssignableFrom(that) => this is same or super to that
313 // => this is at least as general as that
314 // => that may be subtype of this
315
316 if (!(getLineClass().isAssignableFrom(info.getLineClass()))) {
317 return false;
318 }
319
320 return true;
321 }
322
323 /**
324 * Obtains a textual description of the line info.
325 * @return a string description
326 */
327 public String toString() {
328
329 String fullPackagePath = "javax.sound.sampled.";
330 String initialString = new String(getLineClass().toString());
331 String finalString;
332
333 int index = initialString.indexOf(fullPackagePath);
334
335 if (index != -1) {
336 finalString = initialString.substring(0, index)
337 + initialString.substring(
338 (index + fullPackagePath.length()),
339 initialString.length());
340 } else {
341 finalString = initialString;
342 }
343
344 return finalString;
345 }
346
347 } // class Info
348
349 } // interface Line
|