Introduction:

This SDK contains a JNI example of using the 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
    NSLTerm.java     - Java code for interactive licensing example.
                        NOTE - This example uses ansi escape sequences
                        to move the cursor in the console. Windows does
                        not support this some of the screen will be
                        somewhat garbled there.  This will eventually
                        be fixed.

    libShafer.so OR libShafer.dylib OR Shafer.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 V10Example.java the NSA/NSL library name is hardcoded. Either copy your library to this filename in the example directory OR edit the System.loadLibrary command to match.

The V10 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 V10Example.java and specify the location of the Nalpeiron library in the System.loadLibrary call. By default this call looks like:

    System.loadLibrary("Shafer");

Where "Shafer" is the NSA/NSL C library name. By default, Java will look for the library named according to OS (libShafer.so on Linux, libShafer.dylib on OSX, and Shafer.dll on Windows). It will look for such a 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 callNalpLibOpen

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 V10Example

or (Linux)

java -cp ./:./v10src -Djava.library.path=./ V10Example

or (OSX)

java -cp ./:./v10src -Djava.library.path=./ V10Example

or (Windows)

java -cp .\;.\v10src -Djava.library.path=. V10Example

(cygwin)

 java -classpath $(cygpath -wp ".\:.\v10src") -Djava.library.path=. V10Example

The classpath would contain ./ the location of the V10Example.class, ./v10src the location of NALP, NSL, NSA 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 callNalpLibOpen

NALPJAVA_SYMLOAD_ERROR -9002 Most likely a corrupt NSA/NSL library