1.7 - Using in Netbeans projects

jNetPcap is a java project that comes with a required native shared library. The requirement of a native library typically adds confusion and presents difficulty for many as to how properly setup a project in netbeans to reference jNetPcap library correctly.

There are several ways that jNetPcap can be added to your existing java project in Netbeans IDE. Let me briefly outline them here and then lets go through the detailed steps of actually creating a proper build path so your project will compile with jNetPcap.

1. Create a jNetPcap "library" which adds the jnetpcap-*.jar file to the build path
2. Create a new run project config that includes native library
3. Add jnetpcap's jar file to project's build path, but copy the neccessary native library to a system library directory (/usr/lib under unix or \windows\SystemXX under windows).

We recommend approaches #1 and #2 for development.

Note: the native library is only required for running/executing the application. It is not required for compilation. It is needed only at runtime.

First thing first

First thing you have to do is download and install (or unzip) the jNetPcap installation package. You do not have to install (unzip or untar) the installation package under an Netbeans workspace, unless you want to for a specific reasons. The installation can be external to the workspace. Since each jNetPcap installation package installs under a unique directory path, you can easily have multiple versions of the library and switch between them when needed. Both installable and extractable unix and windows packages are provided. Under unix the packager installed packages are intended for production environments, that have a jNetPcap requirement. At same time the JAR and unzip packages are provided incase you need multiple versions of the library where you can extract on your own and easily switch between them.

In the below examples we are going to assume that we extracted jnetpcap library under "G:\libs" directory (on a windows platform). For unix you can assume a home directory based path "$HOME/libs" or something similar. In the "libs" directory we installed the binary jnetpcap-1.4.b0004-1.win32.zip, the source package jnetpcap-src-1.4.b0004-1.zip and jnetpcap-javadoc-1.4.b0004-1.zip. We further unzipped only the binary package jnetpcap-1.4.b0001-1.win32.zip to that directory. The other packages remain in their zipped up form. Netbeans knows how to read them archived.

We now have the following files and directories under "g:\libs":

The jar and .dll files are directly under the "jnetpcap-1.4.b0004-1" directory.

Setting up a new library under Netbeans

The recommended way to setup environment is to setup a new global library under "Libraries". This library will only contain the path to the jnetpcap-*.jar file. It can be added to any netbeans project which will then have access to jnetpcap API.

Assuming that you have already created a new java project, we now create a new library definition for netbeans library manager.

1. Under the "Tools" menu, click on "Libraries" menu item. A "Library Manager" window should show up.
2. If you are setting this up for the first time, library manager does not have a jnetpcap library defined yet. You need to now click on "New Library..." button below the list of existing libraries.
3. A "New Library" window show up. Type in a name for this new library declaration. I suggest using "jnetpcap-1.4" for our example. It is best to include version number of jnetpcap incase you want to setup more then one library and easily switch between them. For "Library Type" selection box, choose "Class Libraries".

   Click OK

4. Now we can define the rest of the elements that make up this library. Click on the "Classpath" tab and then click "Add JAR/Folder..." button. When file browser comes up, navigate to "g:\libs\jnetpcap-1.4-1" directory and select the jar file "jnetpcap-1.4.b0004-1.jar". Close the browser window by clicking "Add JAR/Fold" button. You should now wee the absolute path to "jnetpcap-1.4.b0004-1.jar" file listed under "Library Classpath:" pane.
5. Next click on "Sources" tab. Browser window shows up again. You should be 1 level up from where the -src package resides, so just hit the "UP array/folder" to go up 1 level. Select "jnetpcap-src-1.4.b0004-1.zip" file and click "Add JAR/Folder" button to exit and commit.
6. Next click on "Javadoc" tab. Browser window shows up again. Now select the "jnetpcap-javadoc-1.4.b0004-1.zip" file and click "Add JAR/Folder" button to exit and commit.
7. Dismiss the "Library Manager" window with a click on "OK" button.
8. Now we apply the library to our java project. Under project explorer, right click on the "Libraries" element and select "Add Library" or "Properties" or choose from menu "File->Project Properties" and select libraries section.
9. From the "Add Library" window, choose our newly created library "jnetpcap-1.4" and click "Add Library" button at the bottom. The window should disappear, and if you expand the "Libraries" element under project explorer, you should see our "jnetpcap-1.4" jar file on the libraries classpath.

Now we have setup our "library" for compilation. You should be able to now to have access to full jnetpcap API, go into jnetpcap methods to view their source and look at their javadocs directly from netbeans editor.

Next we need to setup a "run" configuration so that our application finds the require native library (.dll on windows, .so on unix/linux).

1. Select from the menu "Run->Setup Project Configuration->Customize...". This will bring up a "Project Properties" window.
2. Click on "New..." button to the right of the "Configuration:" selection box. Enter a new "Configuration Name". Again I would recommend using "jnetpcap-1.4 config" to specify that we are setting up for jnetpcap 1.4 runtime environment. Click "OK" button to dismiss.
3. Now in the "VM Options:" text field, we need to enter the following options"
   

   -Djava.library.path="g:\libs\jnetpcap-1.4.b0004-1"
   

   Notice the double-quotes around the path and the minus D (-D) option. Do not forget either. Lastly notice, we entered the name of the directory, not the name of the .dll library itself.
   Now Click "OK" to dismiss.

We are now ready to run our jnetpcap application. Netbeans set our run configuration to "jnetpcap-1.4 config" automatically. We did not modify the "default" config so that we can easily switch back to "default" config through menus or the selection config box on the "Run" toolbar. We can also create other run configs this way that point to other jnetpcap versions and easily switch between them. Just remember to switch both the "library" and the "run" config to the same versions.