For this example, we will use Netbeans to develop the Java library. We will then use the javah command-line tool (or ANT task) to generate the C header file for our library. Then we will create a new Xcode project to develop the Objective-C portions, and add the header file that was generated by javah to the project.

For the Java stub, we don't require any special type of netbeans project. You can add native methods to any class in any Java project. They will compile fine even if the native methods haven't been implemented yet. The linking doesn't happen until runtime. The file structure for this example is as follows:

Figure 1. Project structure as shown in netbeans project explorer

The contents of the NSSavePanel class is as follows:

package ca.weblite.jniexample;

/**
 * A wrapper class for the Native save panel in OS X
 * @author shannah
 */
public class NSSavePanel {
    
    public static boolean loaded = false;
    static {
        try {
            System.loadLibrary("savepanel");
            loaded = true;
        } catch (UnsatisfiedLinkError err){
            throw new RuntimeException(err);
        }
    }
    
    public native String saveDialog(String title, String extension);
    
}

Let's look at this example piece by piece, starting with the last part: the native method definition:

public native String saveDialog(String title, String extension);

This is the stub for the native method that will be defined in our C-library. This looks the same as a normal Java method signature except for two things:

Now, let's look at the first part of this class definition:

public static boolean loaded = false;
static {
    try {
        System.loadLibrary("savepanel");
        loaded = true;
    } catch (UnsatisfiedLinkError err){
        throw new RuntimeException(err);
    }
}

This is the code that actually loads the native library that we are going to create. We place this in a static block so that it runs before any code in the class does, and thus should have happened by the time any call is made to the saveDialog method. You actually have quite a bit of flexibility in how and when you load your library. In some cases you may have one large library that contains all of your native method definitions. Then you would probably load this from a central location, then Java would look there for your native method definitions. All that matters is that some library containing your method definition has been loaded a some point at runtime.

The key ingredient here is the System.loadLibrary() call. It will look in all of the library path locations (specified in the java.library.path System.property) to find a library named libsavepanel.dylib. It it finds it and it is able to load it successfully then execution proceeds smoothly. If, for some reason, it fails to find or load the library, it will throw an UnsatisfiedLinkError, which you can catch and handle however you like. In this case we are wrapping it and just throwing a RuntimeException. In practice you should probably handle this with a bit more grace and fall back to some default behavior.

After you have created the java stub, we can generate the C-header files using the javah tool. In this example we're actually going to use the javah ant task. That way the header will automatically be generated every time we compile the project in Netbeans.

Modify the build.xml file of your Netbeans project by adding the following before the closing </project> tag:

<target name="-post-compile">
        <javah 
            destdir="./build" 
            force="yes" 
            class="ca.weblite.jniexample.NSSavePanel" 
            classpath="./build/classes"
        />
</target>

This basically says that we're going to generate a header file to be saved inside the ./build directory for the Java class "ca.weblite.jni.example.NSSavePanel". Now, after compiling our project we should see the file ca_weblite_jniexample_NSSavePanel.h as shown in the Netbeans file explorer below:

Figure 2. The header .h file saved inside the build directory after compiling.

The contents of the ca_weblite_jniexample_NSSavePanel.h file are as follows:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class ca_weblite_jniexample_NSSavePanel */

#ifndef _Included_ca_weblite_jniexample_NSSavePanel
#define _Included_ca_weblite_jniexample_NSSavePanel
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     ca_weblite_jniexample_NSSavePanel
 * Method:    saveDialog
 * Signature: (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;
 */
JNIEXPORT jstring JNICALL Java_ca_weblite_jniexample_NSSavePanel_saveDialog
  (JNIEnv *, jobject, jstring, jstring);

#ifdef __cplusplus
}
#endif
#endif

A Description of the Code. There really isn't a lot going on here. The key line to focus on here is the method signature:

JNIEXPORT jstring JNICALL Java_ca_weblite_jniexample_NSSavePanel_saveDialog
  (JNIEnv *, jobject, jstring, jstring);

Some key points to observe:

Finally, we can proceed to build our native library in Xcode. For this example, I'm using Xcode 4.4.

Step one is to open Xcode and start a new project.

Figure 3. 

Select the "Cocoa Library" option as we wish to distribute our library as a dynamic library (.dylib).

Click Next

Figure 4. 

On this pane, we enter the product details. For convenience, I'm naming the product "libsavepanel", so that it will produce a library named "libsavepanel.dylib" when it is built automatically. You could, of course, just rename the library later or change a setting in Xcode if you want to name your product something else.

Click "Next" to select a location to save the project. Once you have selected a location, Xcode should open the empty project for you.

The project explorer on the left column of the Xcode UI will show the file structure of the project as follows:

Figure 5. 

Since our project will depend on some libraries in the Java development kit (e.g. jni.h), we will need to add the the headers in the JDK's include directory to our project's header search path. As of OS X 10.7, all of your JDK libraries will be located in the /Library/Java/JavaVirtualMachines directory. You can either add the full path to JDK's include directory, or you can copy the include directory into your project folder, and then add that copy to your header search path. For this example, we'll copy it into our project directory so that the project is more portable (i.e. we won't have to depend on the installation location of the JDK in order to build our library.

We'll do this in a few steps:

Now that our project is created, we proceed by adding the header file that we generated for our JNI library. Right-click (or control-click) on the libsavepanel folder in the project explorer of the Xcode project to reveal the context menu. Then select the option "Add Files to libsavepanel..."

Figure 8. 

Then select the ca_weblite_jniexample_NSSavePanel.h file that was created. Once the file has been added, it should appear in the project explorer as shown below:

Figure 9. 

The implementation of our native method will go inside a .m file that we need to create. We're do that by selecting "File" > "New" > "File" from the top menu bar. And then selecting "Objective-C Class" for the file type:

Figure 10. 

When it prompts you for the class name enter the exact name of your header file (minus the .h). E.g. in this case our class name will be "ca_weblite_jniexample_NSSavePanel".

Now that we have our objective-c implementation file, let's delete the contents and create an empty function to correspond with the definition in our header file:

#include "ca_weblite_jniexample_NSSavePanel.h"

JNIEXPORT jstring JNICALL Java_ca_weblite_jniexample_NSSavePanel_saveDialog
(JNIEnv * env, jobject jthis, jstring title, jstring extension){
    
    return NULL;
}

Essentially I created this method definition by copying the signature from the header file, then adding parameter names to the parameter types.

At this point, we have enough to at least test and make sure that our library can be loaded and used properly. Begin by building the Xcode project ("Project" > "Build"). Then right click on the libsavepanel.dylib item in the "Products" folder of the Xcode project explorer, and select "Show in Finder".

Figure 11. 

This will allow us to copy the dylib file into our Java project directory. After copying the libsavepanel.dylib file into our JNIExample project directory (the Netbeans project), our project directory will look like:

Figure 12. 

At this point we have a bare-bones JNI module where the native method only returns NULL. This is a good time to test our module out and make sure that it, at least, is loaded properly by our Java application. Let's add a main() method to our NSSavePanel class so that we can test out our module.

public static void main(String[] args){
    new JFrame(); // Necessary to start the windowing system
    NSSavePanel panel = new NSSavePanel();
    String result = panel.saveDialog("Select a file", "pdf");
    System.out.println("The result was "+result);
}

Now, if you run this file from Netbeans, you should see the following output:

run:
The result was null
BUILD SUCCESSFUL (total time: 0 seconds)

So you can see that our native method returned null, just as expected.

Now that we know that our library is loading properly, it is all down hill from here. We just need to implement the native method in Objective-C. Before we move into the code, there is one more thing that we need to do with our Xcode project: Add the JavaNativeFoundation framework.

You can add the JavaNativeFramework by right-clicking (or control-clicking) on the Frameworks folder in your Xcode project explorer, and selecting "Add files to libsavepanel...". Then, in the file dialog, browse to the JavaNativeFoundation.framework file located as /System/Library/Frameworks/JavaVM.framework/Frameworks

After adding the JavaNativeFoundation framework to your project, the "Frameworks" folder will look like:

Figure 13. 

Now we are ready to do some coding. After implementing our method, the final ca_weblite_jniexample_NSSavePanel.m file content is:

#include "ca_weblite_jniexample_NSSavePanel.h"
#import "JavaNativeFoundation/JavaNativeFoundation.h"
#import "AppKit/AppKit.h"

JNIEXPORT jstring JNICALL Java_ca_weblite_jniexample_NSSavePanel_saveDialog
(JNIEnv * env, jobject jthis, jstring title, jstring extension){
    
    // Obligatory opening to the JNI method.  Sets up an autorelease pool,
    // and rethrows Objective-C exceptions as Java exceptions.  (Paired
    // with JNF_COCOA_EXT(env) at end of method.
    JNF_COCOA_ENTER(env);
    
    // A jstring container for the output value
    jstring path = NULL;
    
    // Placeholder for the NSString path that will be set inside the block
    __block NSString *nsPath = Nil;;
    
    // Copy the title to an NSString so it an be used safely inside the block
    // even if it is on a different thread
    NSString *nsTitle = JNFJavaToNSString(env, title);
    
    // Copy the extension into an NSString so it can be used safely inside
    // the block even if it is on a different thread
    NSString *cocoaExtension = JNFJavaToNSString(env, extension);
    
    
    // Create a block for the code that will create and interact with
    // the NSSavePanel so that it can be run on a different thread.  All
    // interaction with the NSSavePanel class needs to be on the main application
    // thread, so if this method is accessed on a different thread (e.g.
    // the AWT event thread, we'll need to block and run this code on the
    // main application thread.
    void (^block)(void);
    block = ^(void){
        // This block's code must ONLY ever be run on the main
        // application thread.
        
        NSSavePanel *panel = [NSSavePanel savePanel];
        NSArray *types = [NSArray arrayWithObjects: cocoaExtension,nil];
        [panel setAllowedFileTypes: types];
        [panel setCanSelectHiddenExtension:TRUE];
        [panel setExtensionHidden:TRUE];
        [panel setTitle: nsTitle];
        if ( [panel runModal] == NSFileHandlingPanelOKButton ){
            // The user clicked OK in the file save dialog, so we
            // now save the user's file path selection in the nsPath.
            NSURL * out = [[panel URL] filePathURL];
            
            // Set the nsPath so that it can be accessed outside this
            // block after it is run.  We call retain on the string
            // so that it won't be destroyed after the block is
            // finished executing.
            nsPath = [[out path] retain];
        }
    };
    
    // Check if this is already running on the main thread.
    if ( [NSThread isMainThread]){
        // We are on the main thread, so we can execute the block directly.
        block();
    } else {
        // We are not on the main thread so we need to run the block on the
        // main thread, and wait for it to complete.
        [JNFRunLoop performOnMainThreadWaiting:YES withBlock:block];
    }
    
    
    if ( nsPath != nil ){
        // Since nsPath is Not nil, it looks like the user chose a file
        // Copy the NSString path back to the jstring to be returned
        // from the method.
        path = JNFNSToJavaString(env, nsPath);
        
        // Release the nsPath to prevent memory leak.
        [nsPath release];
    }
    
    // Return the path.  This may be null
    return path;
    
    // Matching the opening JNF_COCOA_ENTER(env) at the beginning of the method.
    JNF_COCOA_EXIT(env);
    
    // It is necessary to return NULL here in case there was some failure or
    // exception that prevented us from reaching the return statements inside
    // the JNF_COCOA_ENTER/EXIT region.
    return NULL;

}

This source code is the result of a few iterations, so it requires some explanation.

We're done now. It's time to test it, so we'll build the Xcode project, copy the libsavepanel.dylib file into the JNIExample directory (i.e. the Netbeans project), then try to run the NetBeans test. It should open up a save dialog as follows:

Figure 14. 

And if you enter a file name, then the dialog will close and you should see the following output in the console:

run:
The result was /Users/shannah/Downloads/testdocument.pdf
BUILD SUCCESSFUL (total time: 1 minute 6 seconds)