(MS Windows)
How to Load a Java Native/Dynamic Library (DLL)

There are several ways to make it possible for the Java runtime to find and load a dynamic library (DLL) at runtime. I will list them briefly here, followed by examples and further explanation below.

  1. Call System.load to load the DLL from an explicitly specified absolute path.
  2. Copy the DLL to one of the paths already listed in java.library.path
  3. Modify the PATH environment variable to include the directory where the DLL is located.
  4. Specify the java.library.path on the command line by using the -D option.
  5. If using Eclipse, set the java.library.path in Eclipse for development/debugging.

Note: To help resolve an UnsatisfiedLinkError Runtime Error, see How to Handle the UnsatisfiedLinkError Runtime Error in Java

1. Call System.load to load the DLL from an explicitly specified absolute path.

This choice removes all uncertainty, but embeds a hard-coded path within your Java application. Example:

import com.chilkatsoft.CkZip;

public class Test {
	
  static {
    try {
    	System.load("C:/chilkatJava/chilkat.dll");
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load.\n" + e);
      System.exit(1);
    }
  }

  public static void main(String argv[]) 
  {
    CkZip zip = new CkZip();
    System.out.println(zip.version());    
  }
}

2. Copy the DLL to one of the paths already listed in java.library.path

To see the current value of the PATH environment variable, open a MS-DOS prompt and type:

echo %PATH%

Another way of viewing the java.library.path is to run this Java code:

String property = System.getProperty("java.library.path");
StringTokenizer parser = new StringTokenizer(property, ";");
while (parser.hasMoreTokens()) {
    System.err.println(parser.nextToken());
    }

Note: The java.library.path is initialized from the PATH environment variable. The directories may be listed in a different order, and the current directory "." should be present in java.library.path, but may not be listed in the PATH environment variable.

The loadLibrary method may be used when the directory containing the DLL is in java.library.path. To load "chilkat.dll", call System.loadLibrary("chilkat"), as shown here:

import com.chilkatsoft.CkZip;

public class Test {
	
  static {
    try {
    	
    	System.loadLibrary("chilkat");
    	
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load.\n" + e);
      System.exit(1);
    }
  }
	
  public static void main(String argv[])
  	{
    CkZip zip = new CkZip();
    System.out.println(zip.version());
	}
  }

3. Modify the PATH environment variable to include the directory where the DLL is located.

Do this by modifying the PATH environment variable from the Windows Control Panel.

Set PATH on Windows XP:

  1. Start -> Control Panel -> System -> Advanced
  2. Click on Environment Variables, under System Variables, find PATH, and click on it.
  3. In the Edit windows, modify PATH by adding the location of the class to the value for PATH. If you do not have the item PATH, you may select to add a new variable and add PATH as the name and the location of the class as the value.
  4. Close the window.
  5. Reopen Command prompt window, and run your java code.

Set Path on Windows Vista:

  1. Right click "My Computer" icon
  2. Choose "Properties" from context menu
  3. Click "Advanced" tab ("Advanced system settings" link in Vista)
  4. In the Edit windows, modify PATH by adding the location of the class to the value for PATH. If you do not have the item PATH, you may select to add a new variable and add PATH as the name and the location of the class as the value.
  5. Reopen Command prompt window, and run your java code.

Important: Setting the PATH environment variable from a MS-DOS command prompt has no effect on java.library.path. For example, this does not work:

set PATH=c:\chilkatJava;%PATH%
java Test

Also, modifying the java.library.path from within Java code does not work either:

  static {
    try {
    	// Adding a directory to java.library.path here will not change anything.
    	// System.loadLibrary will still look in the directories listed in java.library.path
    	// as it existed at the very start of the program.
    	// The extra directory path added to java.library.path will not
    	// be searched by loadLibrary.
    	
    	String libpath = System.getProperty("java.library.path");
    	libpath = libpath + ";C:/chilkatJava";
    	System.setProperty("java.library.path",libpath);
    	
    	System.loadLibrary("chilkat");
    	
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load.\n" + e);
      System.exit(1);
    }
  }

4. Specify the java.library.path on the command line by using the -D option.

For example:

java -Djava.library.path=c:\chilkatJava TestApp

5. If using Eclipse, set the java.library.path in Eclipse for development/debugging.

  1. Open Project->Properties, select "Java Build Path", click on the "Add External JARs..." button and add the "chilkat.jar"
  2. (still within the Project Properties dialog) Click on the "Run/Debug Settings", select your Java class, then click on the "Edit..." button. Select the "Arguments" tab, then add -Djava.library.path="C:\chilkatJava;${env_var:PATH}" where "C:\chilkatJava" is the directory path containing the "chilkat.dll" file.