-
- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
Sequencer,Synthesizer
public interface MidiDevice extends AutoCloseable
MidiDeviceis the base interface for all MIDI devices. Common devices include synthesizers, sequencers, MIDI input ports, and MIDI output ports.A
MidiDevicecan be a transmitter or a receiver of MIDI events, or both. Therefore, it can provideTransmitterorReceiverinstances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT ports and synthesizers provide receivers. A Sequencer typically provides transmitters for playback and receivers for recording.A
MidiDevicecan be opened and closed explicitly as well as implicitly. Explicit opening is accomplished by callingopen(), explicit closing is done by callingclose()on theMidiDeviceinstance. If an application opens aMidiDeviceexplicitly, it has to close it explicitly to free system resources and enable the application to exit cleanly. Implicit opening is done by callingMidiSystem.getReceiver()andMidiSystem.getTransmitter(). TheMidiDeviceused byMidiSystem.getReceiverandMidiSystem.getTransmitteris implementation-dependent unless the propertiesjavax.sound.midi.Receiverandjavax.sound.midi.Transmitterare used (see the description of properties to select default providers inMidiSystem). AMidiDevicethat was opened implicitly, is closed implicitly by closing theReceiverorTransmitterthat resulted in opening it. If more than one implicitly openingReceiverorTransmitterwere obtained by the application, the device is closed after the lastReceiverorTransmitterhas been closed. On the other hand, callinggetReceiverorgetTransmitteron the device instance directly does not open the device implicitly. Closing theseTransmitters andReceivers does not close the device implicitly. To use a device withReceivers orTransmitters obtained this way, the device has to be opened and closed explicitly.If implicit and explicit opening and closing are mixed on the same
MidiDeviceinstance, the following rules apply:- After an explicit open (either before or after implicit opens), the device will not be closed by implicit closing. The only way to close an explicitly opened device is an explicit close.
- An explicit close always closes the device, even if it also has been opened implicitly. A subsequent implicit close has no further effect.
MidiDevice device = ...; if (!(device instanceof Sequencer) && !(device instanceof Synthesizer)) { // we're now sure that device represents a MIDI port // ... }A
MidiDeviceincludes aMidiDevice.Infoobject to provide manufacturer information and so on.- See Also:
Synthesizer,Sequencer,Receiver,Transmitter
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static classMidiDevice.InfoAMidiDevice.Infoobject contains assorted data about aMidiDevice, including its name, the company who created it, and descriptive text.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidclose()Closes the device, indicating that the device should now release any system resources it is using.MidiDevice.InfogetDeviceInfo()Obtains information about the device, including its Java class andStringscontaining its name, vendor, and description.intgetMaxReceivers()Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.intgetMaxTransmitters()Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.longgetMicrosecondPosition()Obtains the current time-stamp of the device, in microseconds.ReceivergetReceiver()Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.List<Receiver>getReceivers()Returns all currently active, non-closed receivers connected with thisMidiDevice.TransmittergetTransmitter()Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data.List<Transmitter>getTransmitters()Returns all currently active, non-closed transmitters connected with thisMidiDevice.booleanisOpen()Reports whether the device is open.voidopen()Opens the device, indicating that it should now acquire any system resources it requires and become operational.
-
-
-
Method Detail
-
getDeviceInfo
MidiDevice.Info getDeviceInfo()
Obtains information about the device, including its Java class andStringscontaining its name, vendor, and description.- Returns:
- device info
-
open
void open() throws MidiUnavailableException
Opens the device, indicating that it should now acquire any system resources it requires and become operational.An application opening a device explicitly with this call has to close the device by calling
close(). This is necessary to release system resources and allow applications to exit cleanly.Note that some devices, once closed, cannot be reopened. Attempts to reopen such a device will always result in a
MidiUnavailableException.- Throws:
MidiUnavailableException- thrown if the device cannot be opened due to resource restrictionsSecurityException- thrown if the device cannot be opened due to security restrictions- See Also:
close(),isOpen()
-
close
void close()
Closes the device, indicating that the device should now release any system resources it is using.All
ReceiverandTransmitterinstances open from this device are closed. This includes instances retrieved viaMidiSystem.- Specified by:
closein interfaceAutoCloseable- See Also:
open(),isOpen()
-
isOpen
boolean isOpen()
Reports whether the device is open.
-
getMicrosecondPosition
long getMicrosecondPosition()
Obtains the current time-stamp of the device, in microseconds. If a device supports time-stamps, it should start counting at 0 when the device is opened and continue incrementing its time-stamp in microseconds until the device is closed. If it does not support time-stamps, it should always return -1.- Returns:
- the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device
-
getMaxReceivers
int getMaxReceivers()
Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.- Returns:
- maximum number of MIDI IN connections, or -1 if an unlimited number of connections is available
-
getMaxTransmitters
int getMaxTransmitters()
Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.- Returns:
- maximum number of MIDI OUT connections, or -1 if an unlimited number of connections is available
-
getReceiver
Receiver getReceiver() throws MidiUnavailableException
Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data. The returned receiver must be closed when the application has finished using it.Usually the returned receiver implements the
MidiDeviceReceiverinterface.Obtaining a
Receiverwith this method does not open the device. To be able to use the device, it has to be opened explicitly by callingopen(). Also, closing theReceiverdoes not close the device. It has to be closed explicitly by callingclose().- Returns:
- a receiver for the device
- Throws:
MidiUnavailableException- thrown if a receiver is not available due to resource restrictions- See Also:
Receiver.close()
-
getReceivers
List<Receiver> getReceivers()
Returns all currently active, non-closed receivers connected with thisMidiDevice. A receiver can be removed from the device by closing it.Usually the returned receivers implement the
MidiDeviceReceiverinterface.- Returns:
- an unmodifiable list of the open receivers
- Since:
- 1.5
-
getTransmitter
Transmitter getTransmitter() throws MidiUnavailableException
Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data. The returned transmitter must be closed when the application has finished using it.Usually the returned transmitter implements the
MidiDeviceTransmitterinterface.Obtaining a
Transmitterwith this method does not open the device. To be able to use the device, it has to be opened explicitly by callingopen(). Also, closing theTransmitterdoes not close the device. It has to be closed explicitly by callingclose().- Returns:
- a MIDI OUT transmitter for the device
- Throws:
MidiUnavailableException- thrown if a transmitter is not available due to resource restrictions- See Also:
Transmitter.close()
-
getTransmitters
List<Transmitter> getTransmitters()
Returns all currently active, non-closed transmitters connected with thisMidiDevice. A transmitter can be removed from the device by closing it.Usually the returned transmitters implement the
MidiDeviceTransmitterinterface.- Returns:
- an unmodifiable list of the open transmitters
- Since:
- 1.5
-
-