uk.co.xfactorylibrarians.coremidi4j

Class Loader

java.lang.Object

uk.co.xfactorylibrarians.coremidi4j.Loader

public class Loader
extends Object

Loads the native library when we are running on a Mac. If necessary, extracts a copy of the library from our jar file to a temporary directory, to save the user the trouble of having to install it on their system. Arranges for that directory to be deleted when we exit.

Inspired by the techniques used by usb4java, and the loader written by Klaus Raimer, k@ailis.de . See http://usb4java.org for the web site for the project and https://github.com/usb4java/usb4java for the GitHub repository.

Author:

James Elliott

Field Summary

Fields

Modifier and Type	Field and Description
private static boolean	available Indicates whether the library was successfully loaded, which implies we are on a Mac and ready to operate.
private static int	BUFFER_SIZE How large a buffer should be used for copying the dynamic library out of the jar.
private static boolean	loaded Indicates whether we have tried to load the library.
static String	NATIVE_LIBRARY_NAME The file name of our native library.
private static File	tempDir The temporary directory we will use to extract the native library.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Loader() Prevent instantiation.

Method Summary

Modifier and Type	Method and Description
private static void	copy(InputStream input, File output) Copies the specified input stream to the specified output file.
private static File	createTempDirectory() Creates the temporary directory used for unpacking the native library.
static boolean	isAvailable() Checks whether CoreMidi4J is available on the current system, in other words whether it is a Mac OS X system and the native library was loaded successfully.
private static boolean	isMacOSX() Check that we are running on Mac OS X.
static void	load() Tries to load our native library.
private static String	locateLibrary() Locates the native library, extracting a temporary copy from our jar it does not already exist in the file system.

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE

private static final int BUFFER_SIZE

How large a buffer should be used for copying the dynamic library out of the jar.

See Also:

Constant Field Values

NATIVE_LIBRARY_NAME

public static final String NATIVE_LIBRARY_NAME

The file name of our native library.

See Also:

Constant Field Values

tempDir

private static File tempDir

The temporary directory we will use to extract the native library.

loaded

private static boolean loaded

Indicates whether we have tried to load the library.

available

private static boolean available

Indicates whether the library was successfully loaded, which implies we are on a Mac and ready to operate.

Constructor Detail

Loader

private Loader()

Prevent instantiation.

Method Detail

isMacOSX

private static boolean isMacOSX()

Check that we are running on Mac OS X.

Returns:

true if the OS is OS X, otherwise false

createTempDirectory

private static File createTempDirectory()
                                 throws CoreMidiException

Creates the temporary directory used for unpacking the native library. This directory is marked to be deleted when the JVM exits.

This requires review. There is a method java.nio.file.Files.createTempDirectory that creates a temporary directory. However, java.io.File.createTempFile(String,String) creates a file in the default temp directory.

This method creates a temporary directory named coreMidi4J in the default temp directory. Other code then places the dynamically linked library in the coreMidi4J directory. Both the dynamically linked library file and the directory use File.deleteOnExit(). This should work since they will be deleted in reverse order. However, unexpected crashes could leave the system in a bad state where some files are not deleted.

Returns:

The temporary directory for the native library.

Throws:

CoreMidiException - if there is a problem communicating with CoreMIDI

See Also:

File.delete(), File.deleteOnExit()

copy

private static void copy(InputStream input,
                         File output)
                  throws IOException

Copies the specified input stream to the specified output file.

Parameters:

input - The input stream to be copied.

output - The output file to which the stream should be copied.

Throws:

IOException - If the copy failed.

locateLibrary

private static String locateLibrary()
                             throws CoreMidiException

Locates the native library, extracting a temporary copy from our jar it does not already exist in the file system.

Returns:

The absolute path to the existing or extracted library.

Throws:

CoreMidiException - if there is a problem finding the library

load

public static void load()
                 throws CoreMidiException

Tries to load our native library. Can be safely called multiple times; duplicate attempts are ignored. This method is automatically called whenever any CoreMidi4J class that relies on JNI is loaded. If you need to do it earlier (to catch exceptions for example, or check whether the native library can be used), simply call this method manually.

Throws:

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

isAvailable

public static boolean isAvailable()
                           throws CoreMidiException

Checks whether CoreMidi4J is available on the current system, in other words whether it is a Mac OS X system and the native library was loaded successfully. Will attempt to perform that load if it has not yet occurred.

Returns:

true if this is a Mac OS X system and the native library has been loaded successfully.

Throws:

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