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
(package private) 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
(package private) static void ()
           
(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. it loaded successfully, has valid version numbers, and has not been disabled).
(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

static void ()

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
Following copied from interface: cryptix.util.core.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
Following copied from interface: cryptix.util.core.LinkStatus
Throws:
java.lang.UnsatisfiedLinkError - if the library is not being used

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
Following copied from interface: cryptix.util.core.LinkStatus
Parameters:
enable - 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).