public class NativeLibraryManager extends Object
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/pluginsFor example:
vlc/linux-amd64/vlc vlc/linux-amd64/vlc/pluginsUnderneath "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:
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 and Description |
---|
NativeLibraryManager(String installTo)
Create a new native library manager.
|
NativeLibraryManager(String installTo,
int ioBufferSize)
Create a new native library manager.
|
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.
|
public NativeLibraryManager(String installTo)
installTo
- name of the directory to install the files topublic NativeLibraryManager(String installTo, int ioBufferSize)
installTo
- name of the directory to install the files toioBufferSize
- size of the file input/output bufferpublic void addEventListener(NativeLibraryManagerEventListener listener)
listener
- listener to addpublic void removeEventListener(NativeLibraryManagerEventListener listener)
listener
- listener to removepublic String getInstallTo()
public void unpackNativePackage()
RuntimeException
- if an error occurs, such as no native resource package foundpublic boolean purge()
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.
true
if all files and directories were deleted, otherwise false
Copyright © 2009-2012 Caprica Software Limited. All Rights Reserved.