uk.co.xfactorylibrarians.coremidi4j

Class CoreMidiDeviceProvider

java.lang.Object

javax.sound.midi.spi.MidiDeviceProvider

uk.co.xfactorylibrarians.coremidi4j.CoreMidiDeviceProvider

All Implemented Interfaces:

CoreMidiNotification

public class CoreMidiDeviceProvider
extends MidiDeviceProvider
implements CoreMidiNotification

The OS X CoreMIDI Device Provider

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	CoreMidiDeviceProvider.MidiProperties

Field Summary

Fields

Modifier and Type	Field and Description
private static int	DEVICE_MAP_SIZE
private static CoreMidiDeviceProvider.MidiProperties	midiProperties

Constructor Summary

Constructors

Constructor and Description
CoreMidiDeviceProvider() Class constructor

Method Summary

Modifier and Type	Method and Description
static void	addNotificationListener(CoreMidiNotification listener) Adds a notification listener to the listener set maintained by this class.
private void	buildDeviceMap() Builds the device map
private int	getDestination(int destinationIndex) Gets the specified MIDI Destination EndPoint (JNI).
MidiDevice	getDevice(MidiDevice.Info info) Gets the MidiDevice specified by the supplied MidiDevice.Info structure
MidiDevice.Info[]	getDeviceInfo() Gets information on the installed Core MIDI Devices
static String	getLibraryVersion() Determine the version of the library which is being used.
(package private) static CoreMidiClient	getMIDIClient() Gets the CoreMidiClient object
static MidiDevice.Info[]	getMidiDeviceInfo() Obtains an array of information objects representing the set of all working MIDI devices available on the system.
private CoreMidiDeviceInfo	getMidiDeviceInfo(int reference) Gets a MidiDevice.Info class for the specified reference (JNI).
private int	getNumberOfDestinations() Gets the number of destinations supported by the system
private int	getNumberOfSources() Gets the number of sources supported by the system
(package private) static CoreMidiOutputPort	getOutputPort() Gets the output port
private int	getSource(int sourceIndex) Gets the specified MIDI Source EndPoint
private int	getUniqueID(int reference) Gets the unique ID for an object reference (JNI).
private void	initialise() Initialises the system
boolean	isDeviceSupported(MidiDevice.Info info) Checks to see if the required device is supported by this MidiDeviceProvider
static boolean	isLibraryLoaded() Check whether we have been able to load the native library.
void	midiSystemUpdated() Called when a change in the MIDI environment occurs
static void	removeNotificationListener(CoreMidiNotification listener) Removes a notification listener from the listener list maintained by this class

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEVICE_MAP_SIZE

private static final int DEVICE_MAP_SIZE

See Also:

Constant Field Values

midiProperties

private static final CoreMidiDeviceProvider.MidiProperties midiProperties

Constructor Detail

CoreMidiDeviceProvider

public CoreMidiDeviceProvider()
                       throws CoreMidiException

Class constructor

Throws:

CoreMidiException - if there is a problem initializing the provider

Method Detail

initialise

private void initialise()
                 throws CoreMidiException

Initialises the system

Throws:

CoreMidiException - if there is a problem communicating with CoreMIDI

buildDeviceMap

private void buildDeviceMap()
                     throws CoreMidiException

Builds the device map

Throws:

CoreMidiException - if there is a problem communicating with CoreMIDI

getMIDIClient

static CoreMidiClient getMIDIClient()
                             throws CoreMidiException

Gets the CoreMidiClient object

Returns:

The CoreMidiClient object

Throws:

CoreMidiException - if there is a problem communicating with CoreMIDI

getOutputPort

static CoreMidiOutputPort getOutputPort()

Gets the output port

Returns:

the output port

getDeviceInfo

public MidiDevice.Info[] getDeviceInfo()

Gets information on the installed Core MIDI Devices

Specified by:

getDeviceInfo in class MidiDeviceProvider

Returns:

an array of MidiDevice.Info objects

getDevice

public MidiDevice getDevice(MidiDevice.Info info)
                     throws IllegalArgumentException

Gets the MidiDevice specified by the supplied MidiDevice.Info structure

Specified by:

getDevice in class MidiDeviceProvider

Parameters:

info - The specifications of the device we wish to get

Returns:

The required MidiDevice

Throws:

IllegalArgumentException - if the device is not one that we provided

See Also:

MidiDeviceProvider.getDevice(javax.sound.midi.MidiDevice.Info)

isDeviceSupported

public boolean isDeviceSupported(MidiDevice.Info info)

Checks to see if the required device is supported by this MidiDeviceProvider

Overrides:

isDeviceSupported in class MidiDeviceProvider

Parameters:

info - The specifications of the device we wish to check

Returns:

true if the device is supported, otherwise false

See Also:

MidiDeviceProvider.isDeviceSupported(javax.sound.midi.MidiDevice.Info)

midiSystemUpdated

public void midiSystemUpdated()
                       throws CoreMidiException

Called when a change in the MIDI environment occurs

Specified by:

midiSystemUpdated in interface CoreMidiNotification

Throws:

CoreMidiException - if a problem occurs rebuilding the map of available MIDI devices

addNotificationListener

public static void addNotificationListener(CoreMidiNotification listener)
                                    throws CoreMidiException

Adds a notification listener to the listener set maintained by this class. If it is a CoreMidiDeviceProvider, only keep the most recent one, since Java will create many, and we only want to update the device map once when the MIDI environment changes.

Parameters:

listener - The CoreMidiNotification listener to add

Throws:

CoreMidiException - if it is not possible to provide change notifications

removeNotificationListener

public static void removeNotificationListener(CoreMidiNotification listener)
                                       throws CoreMidiException

Removes a notification listener from the listener list maintained by this class

Parameters:

listener - The CoreMidiNotification listener to remove

Throws:

CoreMidiException - when we are unable to offer change notifications

isLibraryLoaded

public static boolean isLibraryLoaded()
                               throws CoreMidiException

Check whether we have been able to load the native library.

Returns:

true if the library was loaded successfully, and we are operational, and false if the library was not available, so we are idle and not going to return any devices or post any notifications.

Throws:

CoreMidiException - if something unexpected happens trying to load the native library on a Mac OS X system.

getLibraryVersion

public static String getLibraryVersion()

Determine the version of the library which is being used.

Returns:

the implementation version of the library, as compiled into the JAR manifest.

Since:

0.9

getMidiDeviceInfo

public static MidiDevice.Info[] getMidiDeviceInfo()

Obtains an array of information objects representing the set of all working MIDI devices available on the system. This is a replacement for javax.sound.midi.MidiSystem.getMidiDeviceInfo(), and only returns fully-functional MIDI devices. If you call it on a non-Mac system, it simply delegates to the javax.sound.midi implementation. On a Mac, it calls that function, but filters out the broken devices, returning only the replacement versions that CoreMidi4J provides. So by using this method rather than the standard one, you can give your users a menu of MIDI devices which are guaranteed to properly support MIDI System Exclusive messages. A returned information object can then be used to obtain the corresponding device object, by invoking javax.sound.midi.MidiSystem.getMidiDevice().

Returns:

an array of MidiDevice.Info objects, one for each installed and fully-functional MIDI device. If no such devices are installed, an array of length 0 is returned.

getNumberOfSources

private int getNumberOfSources()

Gets the number of sources supported by the system

Returns:

The number of sources supported by the system

getNumberOfDestinations

private int getNumberOfDestinations()

Gets the number of destinations supported by the system

Returns:

The number of destinations supported by the system

getSource

private int getSource(int sourceIndex)
               throws CoreMidiException

Gets the specified MIDI Source EndPoint

Parameters:

sourceIndex - The index of the source to get

Returns:

The specified MIDI Source EndPoint

Throws:

CoreMidiException - if the source index is not valid

getDestination

private int getDestination(int destinationIndex)
                    throws CoreMidiException

Gets the specified MIDI Destination EndPoint (JNI).

Parameters:

destinationIndex - The index of the destination to get

Returns:

The specified MIDI Destination EndPoint

Throws:

CoreMidiException - if the destination index is not valid

getUniqueID

private int getUniqueID(int reference)
                 throws CoreMidiException

Gets the unique ID for an object reference (JNI).

Parameters:

reference - The reference to the object to get the UID for

Returns:

The UID of the referenced object

Throws:

CoreMidiException - if there is a problem communicating with CoreMIDI

getMidiDeviceInfo

private CoreMidiDeviceInfo getMidiDeviceInfo(int reference)
                                      throws CoreMidiException

Gets a MidiDevice.Info class for the specified reference (JNI).

Parameters:

reference - The Core MIDI endpoint reference to create a MidiDevice.Info class for

Returns:

The created MidiDevice.Info class

Throws:

CoreMidiException - if the reference is not valid