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