Introduction:

This SDK contains a JNI example of creating a java wrapper to access the Nalpeiron C library. The JNI used in the this example is used both for normal Java access to the library as well as for Android access.

The basic structure of the example is:

Main Dir- 
    v10src/          - Dir containing java files for the NSL/NSA library
    passsrc/         - Dir  containing java files passive licensing

    Makefile         - Linux and Mac makefile
    NalpJavaWin.bat* - Windows bat file for creating example

    V10Example.java  - Java code for V10 NSL/NSA example
    PassExample.java - Java code for passive licensing example

    libPassive.so OR libPassive.dylib OR Passive.dll
        you must place a copy of your stamped library in the example 
        directory or change the path the example uses to load the library.
        If you've renamed the library you must change the System.loadLibrary
        command to reflect the change

INSTRUCTIONS:

To create the example in Linux or Mac type make in top level directory

To create the example in Windows run NalpJavaWin.bat

NOTE: IN PassiveExample.java the PSL library name is hardcoded. Either copy your library to this filename in the example directory OR edit the System.loadLibrary command to match.

The Passive Nalpeiron java libraries contain both the C library and the JNI wrapper. This library is loaded by a System.loadLibrary call in the example Java code. Java is relatively picky about file names and locations. To access the Nalpeiron library you must do one of the following

Call System.load to load the .so from an explicitly specified absolute path.
Modify java.library.path to contain the path to the library and use System.loadLibrary.
Specify the java.library.path on the command line by using the -D option and use System.loadLibrary.

The filename is set by Java based on your OS and the name passed to the load function. LoadLibrary("XXX") or whichever load library is used on that OS (see below). In general, a library must be named libXXX.so on Linux, libXXX.dylib on OSX or XXX.dll on Windows and loaded by name XXX.

NOTE - While JNI uses utf8 to pass character strings back and forth to the Nalpeiron library, it is non-standard utf8. According to the JNI spec

    There are two differences between this format and the
    standard UTF-8 format. First, the null character
    (char)0 is encoded using the two-byte format rather
    than the one-byte format. This means that modified
    UTF-8 strings never have embedded nulls. Second, only
    the one-byte, two-byte, and three-byte formats of
    standard UTF-8 are used. The Java VM does not
    recognize the four-byte format of standard UTF-8; it
    uses its own two-times-three-byte format instead.

Instead of relying on this broken implementation we have chosen to implement explicit conversion to UTF-8 on the way into the library and explicit conversion to Java strings on the way out of the library. This conversion is performed by the JNI wrapper layer and is transparent to the end programmer.

To modify the example:

Edit PassiveExample.java and specify the location of your Nalpeiron library in the System.loadLibrary call. By default this call looks like:

    System.loadLibrary("Passive");

Where "Passive" is the Nalpeiron Passive C library. By default, Java will look for the library named according to OS (libPassive.so on Linux, libPassive.dylib on OSX, and Passive.dll on Windows) and will look for the library in LD_LIBRARY_PATH, directories contained in /etc/ld.so.conf, /lib, and /usr/lib.

To customize the location of library specific files, logging levels, proxy information, etc. you will have to cutomize the library's initialization function through the callPSLLibOpen

To run the example:

A copy of the Nalpeiron library must be present at the location specified by java.library.path. In the following examples, we'll assume the library is in the same location as your java files and modify the java library path on the command line.

If using Sun's Java, from the command prompt:

java PassiveExample

or (Linux)

java -cp ./:./passsrc -Djava.library.path=./ PassiveExample

or (OSX)

java -cp ./:./passsrc -Djava.library.path=./ PassiveExample

or (Windows)

java -cp .\;.\passsrc -Djava.library.path=. PassiveExample

The classpath would contain ./ the location of the PassiveExample.class, ./passsrc the location of NALP, PSL, and nalpError classes, the library path is set to the location of the Nalpeiron Library.

Common Errors:

On Windows Your Nalpeiron library and the jvm must be the same architecture. If they are not, you will get an error similar to

Exception in thread "main" java.lang.UnsatisfiedLinkError:
Can't load IA 32-bit .dll on a AMD 64-bit platform

NALPJAVA_LIBLOAD_ERROR -9001 Most likely called by a missing or corrupt library. Can also be caused by improperly set system or java paths. Or, by the native libraries not matching the architecture of the java runtime. See NOTE above about callPSLLibOpen

NALPJAVA_SYMLOAD_ERROR -9002 Most likely a corrupt PSL library