uk.co.caprica.vlcj.runtime.install

Class NativeLibraryManager

java.lang.Object

uk.co.caprica.vlcj.runtime.install.NativeLibraryManager

public class NativeLibraryManager
extends Object

Implementation of a native library manager.

This class provides assistance where it is often desirable to include native library resources in a jar file that is provided with the application, enabling the application to execute properly without requiring that the native library resources be installed beforehand.

The idea is to package the native library files (in the case of vlc this is the libvlc native library and all of the required plug-in native libraries) into a single jar file, ship that jar file along with the application, and have the application unpack those jars at run-time (or perhaps installation-time).

This will not happen automatically, it is up to each individual client application to determine how this class will be used - for example some clients may wish to use this class to unpack and install the native libraries one time only when they install their application, other applications may like to unpack the native libraries each time the application is executed.

It is often also often desirable to support multiple platforms and this can be achieved in two ways: either include all native libraries for all platforms in a single jar file, or use a number of platform-specific jar files. So long as the jar file is packaged as expected by this class it does not matter which approach you take.

Whatever approach is taken, this class implements the heavy-lifting that is required.

The expected structure of the native library package jar files is described below (where {os.name} and {os.arch} are replaced by system properties):

   vlc/{os.name}-{os.arch}/vlc
   vlc/{os.name}-{os.arch}/vlc/plugins
 

For example:

   vlc/linux-amd64/vlc
   vlc/linux-amd64/vlc/plugins
 

Underneath "plugins" is the regular vlc plug-ins directory structure with multiple nested directories.

Note that these system properties are converted to lower case, so "Linux" becomes "linux".

When unpacked, the structure underneath the "install to" directory will be (in part):

   /libvlc.so
   /libvlccore.so
   /vlc/
   /vlc/plugins/
 

The prefix vlc/{os.name}-{os.arch} in the package file is stripped from each file name before installing locally.

Also as stated above, underneath "plugins" will be the regular vlc plug-in directory structure.

The native library search path should therefore be set to the "install to" directory of this native library manager. This is the responsibility of the client application, just because this native library manager unpacks the native libraries does not ensure that they will be picked up and used at run-time.

On Linux at least, this is still not yet quite enough - the "install to" directory must be made known by one of the usual mechanisms for setting operating system shared library paths, this includes either:

• Setting the LD_LIBRARY_PATH environment variable to the "install to" directory;
• Adding the "install to" directory to the "/etc/ld.so.conf" file;
• Adding a new file to "/etc/ld.so.conf.d" that specifies the "install to" directory;
• Install the libraries to an already well-known directory such as "/usr/lib".

Of these options, only the first one would not require root privileges.

As before, setting the operating system shared library path in this way would be the responsibility of the client application.

It is possible to register an event listener to receive progress updates - this could be useful to display during a splash-screen or a dialog box when starting the application.

The native library package jars must of course be added to the run-time class-path for the client application.

Implementation notes:

It may be much faster to purge the installation directory each time (rather than overwriting) before unpacking new resources.

Be very careful with purge() since it will delete recursively the entire contents of the native library installation directory no matter what it may contain.

Users of this class should expect that RuntimeException will be thrown if an error occurs.

Here is a partial example showing the structure required for a native library package jar file:

   vlc/
   vlc/linux-amd64/
   vlc/linux-amd64/libvlc.so
   vlc/linux-amd64/libvlc.so.5
   vlc/linux-amd64/libvlc.so.5.1.0
   vlc/linux-amd64/libvlccore.so.5
   vlc/linux-amd64/libvlccore.so
   vlc/linux-amd64/libvlccore.so.5.0.0
   vlc/linux-amd64/vlc/
   vlc/linux-amd64/vlc/lua/
   vlc/linux-amd64/vlc/lua/meta/
   vlc/linux-amd64/vlc/lua/meta/fetcher/
   vlc/linux-amd64/vlc/lua/meta/fetcher/tvrage.luac
   vlc/linux-amd64/vlc/lua/meta/reader/
   vlc/linux-amd64/vlc/lua/meta/reader/filename.luac
   vlc/linux-amd64/vlc/plugins/
   vlc/linux-amd64/vlc/plugins/access/
   vlc/linux-amd64/vlc/plugins/access/libaccess_imem_plugin.so
   vlc/linux-amd64/vlc/plugins/access/libaccess_rar_plugin.so
   ...
 

Constructor Summary

Constructors

Constructor and Description
NativeLibraryManager(String installTo) Create a new native library manager.
NativeLibraryManager(String installTo, int ioBufferSize) Create a new native library manager.

Method Summary

Methods

Modifier and Type	Method and Description
void	addEventListener(NativeLibraryManagerEventListener listener) Add a listener to be notified of native library manager events.
String	getInstallTo() Get the name of the installation directory.
boolean	purge() Purge the native library installation directory.
void	removeEventListener(NativeLibraryManagerEventListener listener) Remove a listener being notified of native library manager events.
void	unpackNativePackage() Unpack a package containing native libraries.

Methods inherited from class java.lang.Object

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

Constructor Detail

NativeLibraryManager

public NativeLibraryManager(String installTo)

Create a new native library manager.

Parameters:

installTo - name of the directory to install the files to

NativeLibraryManager

public NativeLibraryManager(String installTo,
                    int ioBufferSize)

Create a new native library manager.

Parameters:

installTo - name of the directory to install the files to

ioBufferSize - size of the file input/output buffer

Method Detail

addEventListener

public void addEventListener(NativeLibraryManagerEventListener listener)

Add a listener to be notified of native library manager events.

Parameters:

listener - listener to add

removeEventListener

public void removeEventListener(NativeLibraryManagerEventListener listener)

Remove a listener being notified of native library manager events.

Parameters:

listener - listener to remove

getInstallTo

public String getInstallTo()

Get the name of the installation directory.

Returns:

installation directory name

unpackNativePackage

public void unpackNativePackage()

Unpack a package containing native libraries.

Throws:

RuntimeException - if an error occurs, such as no native resource package found

purge

public boolean purge()

Purge the native library installation directory.

The installation directory itself and all of it's contents (including all nested directories and their own contents) will be deleted.

Even if this method returns false, some of the files and directories may have been deleted.

Warning: this will without discrimination delete the entire contents of the native library installation directory.

Returns:

true if all files and directories were deleted, otherwise false