MidiDevice


1   /*
2    * @(#)MidiDevice.java  1.38 03/12/19
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.midi;
9   
10  import java.util.List  ;
11  
12   /**
13   * <code>MidiDevice</code> is the base interface for all MIDI devices.
14   * Common devices include synthesizers, sequencers, MIDI input ports, and MIDI
15   * output ports.  
16   *
17   * <p>A <code>MidiDevice</code> can be a transmitter or a receiver of
18   * MIDI events, or both. Therefore, it can provide {@link Transmitter}
19   * or {@link Receiver} instances (or both). Typically, MIDI IN ports
20   * provide transmitters, MIDI OUT ports and synthesizers provide
21   * receivers. A Sequencer typically provides transmitters for playback
22   * and receivers for recording.
23   *
24   * <p>A <code>MidiDevice</code> can be opened and closed explicitly as
25   * well as implicitly. Explicit opening is accomplished by calling
26   * {@link #open}, explicit closing is done by calling {@link
27   * #close} on the <code>MidiDevice</code> instance.
28   * If an application opens a <code>MidiDevice</code>
29   * explicitly, it has to close it explicitly to free system resources
30   * and enable the application to exit cleanly. Implicit opening is
31   * done by calling {@link javax.sound.midi.MidiSystem#getReceiver
32   * MidiSystem.getReceiver} and {@link
33   * javax.sound.midi.MidiSystem#getTransmitter
34   * MidiSystem.getTransmitter}. The <code>MidiDevice</code> used by
35   * <code>MidiSystem.getReceiver</code> and
36   * <code>MidiSystem.getTransmitter</code> is implementation-dependant
37   * unless the properties <code>javax.sound.midi.Receiver</code>
38   * and <code>javax.sound.midi.Transmitter</code> are used (see the
39   * description of properties to select default providers in
40   * {@link javax.sound.midi.MidiSystem}). A <code>MidiDevice</code>
41   * that was opened implicitly, is closed implicitly by closing the
42   * <code>Receiver</code> or <code>Transmitter</code> that resulted in
43   * opening it. If more than one implicitly opening
44   * <code>Receiver</code> or <code>Transmitter</code> were obtained by
45   * the application, the decive is closed after the last
46   * <code>Receiver</code> or <code>Transmitter</code> has been
47   * closed. On the other hand, calling <code>getReceiver</code> or
48   * <code>getTransmitter</code> on the device instance directly does
49   * not open the device implicitly. Closing these
50   * <code>Transmitter</code>s and <code>Receiver</code>s does not close
51   * the device implicitly. To use a device with <code>Receiver</code>s
52   * or <code>Transmitter</code>s obtained this way, the device has to
53   * be opened and closed explicitly.
54   *
55   * <p>If implicit and explicit opening and closing are mixed on the
56   * same <code>MidiDevice</code> instance, the following rules apply:
57   *
58   * <ul>
59   * <li>After an explicit open (either before or after implicit
60   * opens), the device will not be closed by implicit closing. The only
61   * way to close an explicitly opened device is an explicit close.</li>
62   *
63   * <li>An explicit close always closes the device, even if it also has
64   * been opened implicitly. A subsequent implicit close has no further
65   * effect.</li>
66   * </ul>
67   *
68   * To detect if a MidiDevice represents a hardware MIDI port, the
69   * following programming technique can be used:
70   *
71   * <pre>
72   * MidiDevice device = ...;
73   * if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
74   *   // we're now sure that device represents a MIDI port
75   *   // ...
76   * }
77   * </pre>
78   *
79   * <p>
80   * A <code>MidiDevice</code> includes a <code>{@link MidiDevice.Info}</code> object
81   * to provide manufacturer information and so on.
82   *
83   * @see Synthesizer
84   * @see Sequencer
85   * @see Receiver
86   * @see Transmitter
87   *
88   * @version 1.38, 03/12/19
89   * @author Kara Kytle
90   * @author Florian Bomers
91   */
92  
93  public interface MidiDevice {
94  
95  
96      /**
97       * Obtains information about the device, including its Java class and
98       * <code>Strings</code> containing its name, vendor, and description.
99       *
100      * @return device info
101      */
102     public Info getDeviceInfo();
103 
104 
105     /**
106      * Opens the device, indicating that it should now acquire any
107      * system resources it requires and become operational.
108      *
109      * <p>An application opening a device explicitly with this call
110      * has to close the device by calling {@link #close}. This is
111      * necessary to release system resources and allow applications to
112      * exit cleanly.
113      *
114      * <p>
115      * Note that some devices, once closed, cannot be reopened.  Attempts
116      * to reopen such a device will always result in a MidiUnavailableException.
117      *
118      * @throws MidiUnavailableException thrown if the device cannot be
119      * opened due to resource restrictions.
120      * @throws SecurityException thrown if the device cannot be
121      * opened due to security restrictions.
122      *
123      * @see #close
124      * @see #isOpen
125      */
126     public void open() throws MidiUnavailableException  ;
127 
128 
129     /**
130      * Closes the device, indicating that the device should now release
131      * any system resources it is using.
132      *
133      * <p>All <code>Receiver</code> and <code>Transmitter</code> instances
134      * open from this device are closed. This includes instances retrieved
135      * via <code>MidiSystem</code>.
136      * 
137      * @see #open
138      * @see #isOpen
139      */
140     public void close();
141 
142 
143     /**
144      * Reports whether the device is open.
145      *
146      * @return <code>true</code> if the device is open, otherwise
147      * <code>false</code>
148      * @see #open
149      * @see #close
150      */
151     public boolean isOpen();
152 
153 
154     /**
155      * Obtains the current time-stamp of the device, in microseconds.
156      * If a device supports time-stamps, it should start counting at
157      * 0 when the device is opened and continue incrementing its
158      * time-stamp in microseconds until the device is closed.
159      * If it does not support time-stamps, it should always return
160      * -1.
161      * @return the current time-stamp of the device in microseconds,
162      * or -1 if time-stamping is not supported by the device.
163      */
164     public long getMicrosecondPosition();
165 
166 
167     /**
168      * Obtains the maximum number of MIDI IN connections available on this
169      * MIDI device for receiving MIDI data.
170      * @return maximum number of MIDI IN connections, 
171      * or -1 if an unlimited number of connections is available.
172      */
173     public int getMaxReceivers();
174 
175 
176     /**
177      * Obtains the maximum number of MIDI OUT connections available on this
178      * MIDI device for transmitting MIDI data.
179      * @return maximum number of MIDI OUT connections,
180      * or -1 if an unlimited number of connections is available.
181      */
182     public int getMaxTransmitters();
183 
184 
185     /**
186      * Obtains a MIDI IN receiver through which the MIDI device may receive
187      * MIDI data.  The returned receiver must be closed when the application
188      * has finished using it.
189      *
190      * <p>Obtaining a <code>Receiver</code> with this method does not
191      * open the device. To be able to use the device, it has to be
192      * opened explicitly by calling {@link #open}. Also, closing the
193      * <code>Receiver</code> does not close the device. It has to be
194      * closed explicitly by calling {@link #close}.
195      *
196      * @return a receiver for the device.
197      * @throws MidiUnavailableException thrown if a receiver is not available
198      * due to resource restrictions
199      * @see Receiver#close()
200      */
201     public Receiver   getReceiver() throws MidiUnavailableException  ;
202 
203 
204     /**
205      * Returns all currently active, non-closed receivers
206      * connected with this MidiDevice.
207      * A receiver can be removed
208      * from the device by closing it.
209      * @return an unmodifiable list of the open receivers
210      * @since 1.5
211      */
212     List  <Receiver  > getReceivers();
213 
214 
215     /**
216      * Obtains a MIDI OUT connection from which the MIDI device will transmit
217      * MIDI data  The returned transmitter must be closed when the application
218      * has finished using it.
219      *
220      * <p>Obtaining a <code>Transmitter</code> with this method does not
221      * open the device. To be able to use the device, it has to be
222      * opened explicitly by calling {@link #open}. Also, closing the
223      * <code>Transmitter</code> does not close the device. It has to be
224      * closed explicitly by calling {@link #close}.
225      *
226      * @return a MIDI OUT transmitter for the device.
227      * @throws MidiUnavailableException thrown if a transmitter is not available
228      * due to resource restrictions
229      * @see Transmitter#close()
230      */
231     public Transmitter   getTransmitter() throws MidiUnavailableException  ;
232 
233 
234     /**
235      * Returns all currently active, non-closed transmitters
236      * connected with this MidiDevice.
237      * A transmitter can be removed
238      * from the device by closing it.
239      * @return an unmodifiable list of the open transmitters
240      * @since 1.5
241      */
242     List  <Transmitter  > getTransmitters();
243  
244  
245 
246     /**
247      * A <code>MidiDevice.Info</code> object contains assorted
248      * data about a <code>{@link MidiDevice}</code>, including its
249      * name, the company who created it, and descriptive text.
250      *
251      * @see MidiDevice#getDeviceInfo
252      */
253     public static class Info {
254 
255     /**
256      * The device's name.
257      */
258     private String   name;
259 
260     /**
261      * The name of the company who provides the device.
262      */
263     private String   vendor;
264 
265     /**
266      * A description of the device.
267      */
268     private String   description;
269 
270     /**
271      * Device version.
272      */
273     private String   version;
274 
275 
276     /**
277      * Constructs a device info object.
278      *
279      * @param name the name of the device
280      * @param vendor the name of the company who provides the device
281      * @param description a description of the device
282      * @param version version information for the device
283      */
284     protected Info(String   name, String   vendor, String   description, String   version) {
285 
286         this.name = name;
287         this.vendor = vendor;
288         this.description = description;
289         this.version = version;
290     }
291 
292 
293     /**
294      * Reports whether two objects are equal.
295      * Returns <code>true</code> if the objects are identical.
296      * @param obj the reference object with which to compare this
297      * object
298      * @return <code>true</code> if this object is the same as the
299      * <code>obj</code> argument; <code>false</code> otherwise
300      */
301     public final boolean equals(Object   obj) {
302         return super.equals(obj);
303     }
304 
305 
306     /**
307      * Finalizes the hashcode method.
308      */
309     public final int hashCode() {
310         return super.hashCode();
311     }
312 
313 
314     /**
315      * Obtains the name of the device.
316      *
317      * @return a string containing the device's name
318      */
319     public final String   getName() {
320         return name;
321     }
322 
323 
324     /**
325      * Obtains the name of the company who supplies the device.
326      * @return device the vendor's name
327      */
328     public final String   getVendor() {
329         return vendor;
330     }
331 
332 
333     /**
334      * Obtains the description of the device.
335      * @return a description of the device
336      */
337     public final String   getDescription() {
338         return description;
339     }
340 
341 
342     /**
343      * Obtains the version of the device.
344      * @return textual version information for the device.
345      */
346     public final String   getVersion() {
347         return version;
348     }
349 
350 
351     /**
352      * Provides a string representation of the device information.
353 
354      * @return a description of the info object
355      */
356     public final String   toString() {
357         return name;
358     }
359     } // class Info
360 
361 
362 }
363
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags