cryptix.provider.md

Class NativeLink

Implemented Interfaces:
LinkStatus

(package private) final class NativeLink
extends java.lang.Object
implements LinkStatus

A class to handle loading and versioning of native code in a VM-independent way.

SECURITY: this class must be package-private, and not accessible to untrusted code. Therefore the source file must be copied to each package that needs it, with the package statement adjusted accordingly. Make sure that any changes are reflected in all copies.

Copyright © 1997 Systemics Ltd on behalf of the Cryptix Development Team.
All rights reserved.

$Revision: 1.10 $

Authors:
David Hopwood
Raif S. Naffah
Since:
Cryptix 2.2.2

Constructor Summary

NativeLink(String libname, int major, int minor)
Constructs a NativeLink object that can be used to load the given native library.

Method Summary

(package private) boolean
attemptLoad()
Tries to load the native library, if it is enabled.
(package private) void
check(String reason)
If reason is null, this method returns silently.
void
checkNative()
Checks that the native library is being used (i.e.
(package private) void
checkVersion(int major, int minor)
Sets the actual major and minor version numbers of the library.
(package private) void
fail(Throwable e)
Marks the library as having failed a test.
String
getLibraryName()
Returns the library name.
String
getLinkErrorString()
Returns an error string describing why the library failed to load, or null if there was no error.
int
getMajorVersion()
Returns the actual major version number.
int
getMinorVersion()
Returns the actual minor version number.
int
getRequiredMajorVersion()
Returns the required major version number.
int
getRequiredMinorVersion()
Returns the required minor version number.
boolean
isLibraryCorrect()
Returns true if the library was loaded successfully.
boolean
isLibraryLoaded()
Returns true if the library was loaded.
void
setNative(boolean wanted)
Enables or disables the native code.
boolean
useNative()
Returns true if native code is being used.

Constructor Details

NativeLink

(package private)  NativeLink(String libname,
                              int major,
                              int minor)
Constructs a NativeLink object that can be used to load the given native library. libname is the platform-independent part of the name.
Parameters:
libname - the library name
major - the required major version number
minor - the required minor version number

Method Details

attemptLoad

(package private)  boolean attemptLoad()
Tries to load the native library, if it is enabled. Returns true if the library was successfully loaded by this call (but not if it was already loaded).

check

(package private)  void check(String reason)
If reason is null, this method returns silently. Otherwise, an UnsatisfiedLinkError is thrown with reason included in the detail message.

This is useful for handling native methods that return null on success, or an error String on failure.

Parameters:
reason - either null or an error message

checkNative

public void checkNative()
Checks that the native library is being used (i.e. it loaded successfully, has valid version numbers, and has not been disabled).
Specified by:
checkNative in interface LinkStatus

checkVersion

(package private)  void checkVersion(int major,
                                     int minor)
Sets the actual major and minor version numbers of the library. If they are not compatible with the required version numbers passed to the NativeLink constructor, an UnsatisfiedLinkError is thrown.

The major version must match the required major version exactly, and the minor version must be at least the required minor version, in order for the library to be compatible.

Parameters:
major - the actual major version number
minor - the actual minor version number

fail

(package private)  void fail(Throwable e)
Marks the library as having failed a test.
Parameters:
e - the exception that was thrown to indicate the failure.

getLibraryName

public String getLibraryName()
Returns the library name.
Specified by:
getLibraryName in interface LinkStatus

getLinkErrorString

public String getLinkErrorString()
Returns an error string describing why the library failed to load, or null if there was no error.
Specified by:
getLinkErrorString in interface LinkStatus
Returns:
the error string, or null if no error occured

getMajorVersion

public int getMajorVersion()
Returns the actual major version number.
Specified by:
getMajorVersion in interface LinkStatus

getMinorVersion

public int getMinorVersion()
Returns the actual minor version number.
Specified by:
getMinorVersion in interface LinkStatus

getRequiredMajorVersion

public int getRequiredMajorVersion()
Returns the required major version number.
Specified by:
getRequiredMajorVersion in interface LinkStatus

getRequiredMinorVersion

public int getRequiredMinorVersion()
Returns the required minor version number.
Specified by:
getRequiredMinorVersion in interface LinkStatus

isLibraryCorrect

public boolean isLibraryCorrect()
Returns true if the library was loaded successfully.
Specified by:
isLibraryCorrect in interface LinkStatus

isLibraryLoaded

public boolean isLibraryLoaded()
Returns true if the library was loaded. It may or may not be the correct version.
Specified by:
isLibraryLoaded in interface LinkStatus

setNative

public void setNative(boolean wanted)
Enables or disables the native code. By default, native code is used whenever its library can be loaded correctly. This method can be used to disable native linking (and re-enable it) for a specific class.
Specified by:
setNative in interface LinkStatus
Parameters:

useNative

public boolean useNative()
Returns true if native code is being used.
Specified by:
useNative in interface LinkStatus