cryptix.provider.cipher

Class NativeLink

java.lang.Object

cryptix.provider.cipher.NativeLink

All Implemented Interfaces:

LinkStatus

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 $

Since:

Cryptix 2.2.2

Author:

David Hopwood, Raif S. Naffah

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
(package private) boolean	attemptLoad() Tries to load the native library, if it is enabled.
(package private) void	check(java.lang.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(java.lang.Throwable e) Marks the library as having failed a test.
java.lang.String	getLibraryName() Returns the library name.
java.lang.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.

Methods inherited from class java.lang.Object

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

Constructor Detail

NativeLink

NativeLink(java.lang.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 Detail

getRequiredMajorVersion

public int getRequiredMajorVersion()

Description copied from interface: LinkStatus

Returns the required major version number.

Specified by:

getRequiredMajorVersion in interface LinkStatus

getRequiredMinorVersion

public int getRequiredMinorVersion()

Description copied from interface: LinkStatus

Returns the required minor version number.

Specified by:

getRequiredMinorVersion in interface LinkStatus

getLibraryName

public java.lang.String getLibraryName()

Description copied from interface: LinkStatus

Returns the library name.

Specified by:

getLibraryName in interface LinkStatus

getMajorVersion

public int getMajorVersion()

Description copied from interface: LinkStatus

Returns the actual major version number.

Specified by:

getMajorVersion in interface LinkStatus

getMinorVersion

public int getMinorVersion()

Description copied from interface: LinkStatus

Returns the actual minor version number.

Specified by:

getMinorVersion in interface LinkStatus

isLibraryLoaded

public boolean isLibraryLoaded()

Description copied from interface: LinkStatus

Returns true if the library was loaded. It may or may not be the correct version.

Specified by:

isLibraryLoaded in interface LinkStatus

isLibraryCorrect

public boolean isLibraryCorrect()

Description copied from interface: LinkStatus

Returns true if the library was loaded successfully.

Specified by:

isLibraryCorrect in interface LinkStatus

getLinkErrorString

public java.lang.String getLinkErrorString()

Description copied from interface: LinkStatus

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

checkVersion

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

check

void check(java.lang.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

fail

void fail(java.lang.Throwable e)

Marks the library as having failed a test.

Parameters:

e - the exception that was thrown to indicate the failure.

checkNative

public void checkNative()

Description copied from interface: LinkStatus

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

useNative

public boolean useNative()

Description copied from interface: LinkStatus

Returns true if native code is being used.

Specified by:

useNative in interface LinkStatus

setNative

public void setNative(boolean wanted)

Description copied from interface: LinkStatus

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:

wanted - true if native code should be used.

attemptLoad

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).