In this chapter, I present two examples. The first sample program, NativeLogExample, demonstrates the creation of a simple JNI application where Java communicates unidirectionally with an Objective-C object. I find it easiest to learn (or explain) new programming paradigms with simple examples, so this first JNI class is stripped of all extras.

The second example, later in this chapter, details full communication from Java to an NSView and from an NSView to a Java CocoaComponent. The second example is much more complex, so unless you are already familiar with JNI on OS X, don't skip the first example.

The first example follows a shorter list of steps than mentioned previously:

While the steps don't appear much smaller than the preceding list, this first example requires less complex code. Handling the callbacks is rather tricky. Callbacks require several JNI-specific references and attaching/detaching threads. The first example has no callbacks.

JNI has a steep learning curve. Lots of technologies are involved. If you don't understand some basics of C, JNI is nearly impossible to learn. Familiarity with pointers is a must. Be sure to read the "Overview of C Pointers" sidebar for a brief review of C pointers.

int i;

&i

my_function( &i );

int *ip;

int   i = 3;
int *ip = &i;

int  i = 3;
int *ip = &i;
int anotherInt = *ip;

The following example is called native_log_example. The example project is found on the book's Web site. I provide an Ant build.xml file with the project to aid in building the project. Later in this chapter, I go over the build.xml file provided for this project.

The following source is the NativeLogExample class. As with other Java classes, you should put the NativeLogExample class in a file named after the class. In this case, you should name the file NativeLogExample.java. Alternatively, you can open the file from the book's Web site.

The nativeLogExample class contains static blocks and native methods. Unless you have written JNI applications in the past, you likely have never seen or heard of static blocks or native methods in Java programs. Most Java applications have little use for either. However, JNI uses both static blocks and native methods.

The NativeLogExample class demonstrates a static block of Java code and a method with the native label:

package com.genedavis;n
import java.io.File;
import java.io.IOException;
public class NativeLogExample {
   // executed during class load
   static
   {
      // Use System.load() to load directly from a non-system
      // path. Be sure to catch an IOException if used
      // File lib = new File("objc_bin/libNativeLogger.jnilib")
      // System.load( lib.getCanonicalPath() );

      //use System.loadLibrary() when loading from a system
      //library path
      System.loadLibrary("NativeLogger");
   }

   /**
    * It all begins here
    */
   public static void main(String[] args)
   {
         NativeLogExample nl = new NativeLogExample();
         nl.log("Hello world! (of course)");
   }

   // native method call
   private native void log(String message);
}

Static blocks are code blocks that execute when the ClassLoaders loads a class. To use a static block, place the following code outside of all methods, but inside the class definition:

static
{
   // Place initialization code here.
}

Place your code between the curly braces. By convention, position static blocks somewhere near the top of the class, so they are easily noticed. Static blocks execute before any other code, meaning that code in static blocks executes before the main() method is called.

However, avoid static blocks when writing actual production-quality code.

Static blocks execute in the order that they load. This means that static blocks within a class execute in the order they appear. However, if you have static blocks in multiple classes, the order in which the classes load is undefined. Do not make static blocks in one class depend on static blocks in another class.

Static blocks are not very object oriented, so avoid them. However, occasionally you need to perform some class or object initialization before the main() method executes. JNI library loading and initialization of native libraries are two cases where use of static blocks is justified in Java.

The NativeLogExample class uses a static block to load the native library NativeLogger. (I explain creation of the NativeLogger library later in this chapter.) If you look around the example code for a class named exactly "NativeLogger," you will be disappointed.

JNI uses dynamic libraries. On OS X, the naming convention for dynamic libraries is as follows:

lib<library name>.jnilib

When loading a dynamic library for use in JNI, load the library by name and ignore the extras. In the case of a library named NativeLogger, the actual filename for the library is this:

libNativeLogger.jnilib

The call for loading the NativeLogger library is this:

System.loadLibrary("NativeLogger");

Two common ways of loading dynamic libraries exist. If your library is in the system path or specified a known path to the JVM, System.loadLibrary() works fine. The JVM finds the library and loads it. However, if the program knows the location of the library and the library is not in the system path, use the System.load() method.

The System.load() method takes an absolute path as an argument. Do not worry about the absolute path if you only know the relative path. Create a File object from your relative path, and then call getCanonicalPath() on the new File object. This creates an absolute path from your relative path. The only catch (quite literally) is that the process needs to be enclosed in a try-catch to catch potential IOExceptions.

I place one native method in the NativeLogExample class. The method is as follows:

private native void log(String message);

Note that it is not implemented. Native methods are implemented in native C (or C or Objective-C) code. The naming conventions for the native implementation are nasty. You can create the methods signatures by hand, but I do not recommend it. Instead use javah.

Before writing the C implementations of your Java class's native methods, run javah. The javah tool is a command-line tool for creation of C header files from Java classes with native methods.

These are the steps for running javah:

For example, creating a C header for the implementation of the Java NativeLogExample class might look like the following:

javah -classpath java_bin -d objc_src com.genedavis.NativeLogExample

If you want all your JNI method declarations in the same header file, use the -o option instead of the -d option. The -o option specifies the path and name of a header file in which to place all C method signatures.

The JNI header file is generated automatically from the NativeLogExample using javah. I named the file I generated native_log_example_jni.h, and its source follows:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class com_genedavis_NativeLogExample */
#ifndef _Included_com_genedavis_NativeLogExample
#define _Included_com_genedavis_NativeLogExample
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     com_genedavis_NativeLogExample
 * Method:    log
 * Signature: (Ljava/lang/String;)V
 */

JNIEXPORT void JNICALL Java_com_genedavis_NativeLogExample_log
  (JNIEnv *, jobject, jstring);
#ifdef __cplusplus
}
#endif
#endif

This entire header defines only one native method, log(). The actual C method declaration is this:

JNIEXPORT void JNICALL Java_com_genedavis_NativeLogExample_log
  (JNIEnv *, jobject, jstring);

The method name log() in Java becomes this function in C: Java_com_genedavis_NativeLogExample_log()

At first glance, this new name seems overly complex, but the complexity prevents naming collisions. Also, because javah did all the work naming the function, it is not too painful. The name starts with "Java," followed by the package and class name where the native method is initially declared, and is finished off by the actual Java native method name.

When writing JNI bridges to Objective-C, I prefer buffering the Objective-C classes from the JNI interface. I place the C implementations of the Java native methods in a separate C file. I find this buffer prevents purely procedural code from mixing with Object-Oriented code. Generally, you should avoid mixing the two types of programming in the same file. It makes the code more legible.

In the case of this project, I placed the JNI implementation code inside a *.m file. The .m extension indicates that Objective-C is found in the file. Objective-C extends ANSI C, so using Objective-C in a file that is mostly ANSI C is convenient. In this case, Objective-C is providing #import, instantiation of the Objective-C class NativeLogExample, and an object release pool. Usually, C uses #include. When headers are defined improperly, #include can actually include the same library in your compiled code multiple times. Luckily, Objective-C defines the #import that, like the Java import, prevents multiple includes of code without any additional work by you the programmer.

The following source is the implementation of the automatically generated JNI header file. Notice the import of the native_log_example_jni.h. The native_log_example_jni.h header is the header generated from the Java class containing the native log() method. The filename is nle.m. As I mentioned earlier, the lowercase m in the filename extension signifies an Objective-C file.

#import <jni.h>
#import <stdio.h>
#import <Cocoa/Cocoa.h>
#import "native_log_example_jni.h"
#import "NativeLogExample.h"

// This is the entry point from Java to the Objective-C code
JNIEXPORT void JNICALL Java_com_genedavis_NativeLogExample_log
   (JNIEnv * jenv, jobject job, jstring my_jstring)
{
   // Every thread must be wrapped in an NSAutoreleasePool
   // This prevents memory leaks
   NSAutoreleasePool    *pool = [[NSAutoreleasePool alloc] init];

   // converting the jstring to an NSString
   // 1. get a jchar array from the jstring
   // 2. get the length of the jstring
   // 3. instantiate the NSString
   // 4. free the jvm resources (no garbage collector here)
   const jchar *chars = (*jenv)->GetStringChars(jenv, my_jstring, NULL);
   NSUInteger str_len = (*jenv)->GetStringLength(jenv, my_jstring);
   NSString *message = [NSString
                          stringWithCharacters:(UniChar *)chars
                          length:str_len];
   (*jenv)->ReleaseStringChars(jenv, my_jstring, chars);

   // instantiating a NativeLogExample object
   NativeLogExample *nfe = [[NativeLogExample alloc] init];

   // calling the log() method on the NativeLogExample instance
   // passing an NSString to the method log()
   [nfe log: message];

   // destroy instances
   [message release];
   [nfe release];

   // destroying the NSAutoreleasePool
   [pool release];
}

I start the nle.m file by importing two standard headers. They are jni.h and stdio.h. These are both C headers, and as you have guessed, jni.h is required when implementing JNI native methods. Next, I import the Objective-C framework called Cocoa. Finally, I import the two project header files: native_log_example_jni.h and NativeLogExample.h. NativeLogExample.h defines the Objective-C class used in this example.

[NSString stringWithCharacters:
   ( UniChar * ) chars
   length: str_len ];

String.stringWithCharactersLength ( (char[]) chars, str_len );

const jchar *chars = (*jenv)->GetStringChars(
                                             jenv,
                                             my_jstring,
                                             NULL);
NSUInteger str_len = (*jenv)->GetStringLength(jenv, my_jstring);
NSString *message = [NSString
                          stringWithCharacters:(UniChar *)chars
                          length:str_len];
(*jenv)->ReleaseStringChars(jenv, my_jstring, chars);

Objective-C is an OOP language. So of course, objects play a central role in the language. In this section, I discuss Objective-C classes and creation of instances.

On the Java side, CocoaComponent usage consists of a Java class extending CocoaComponent. On the Objective-C side, CocoaComponents consist of an Objective-C class implementing a protocol called AWTCocoaComponent. (Protocols are analogous to Java interfaces.) Because CocoaComponent requires Objective-C classes, I introduce a basic Objective-C class in this first example. I hold off implementing the AWTCocoaComponent protocol until the second JNI example.

Objective-C classes are often placed in one file or split into two files, mostly depending on the style of the programmer and the complexity of the class. Objective-C classes consist of an interface that defines the methods and variables contained by the class and an implementation that implements the interface. When the class is split into two files, the interface is placed in a header file (*.h), along with any #defines and #imports the class needs. The implementation is placed in an Objective-C file (*.m), along with a #import statement importing the class interface. When the class is placed in only one file, the interface and implementation both go in a file with the .m extension.

The Objective-C class I use in the first JNI example exists in two files. The header is in the file NativeLogExample.h. The following is the source for the class interface:

#import <jni.h>
#import <Cocoa/Cocoa.h>
// defining the NativeLogExample class
@interface NativeLogExample : NSObject {
   // instance variable declarations go here
}
// one method named log takes an NSString object
-( void ) log: (NSString *) message ;
@end

The interface starts by importing the Cocoa.h header. JNI uses the jni.h header, but this class lets the nle.m code take care of all the messy JNI. So I do not import jni.h in this interface file. In the next example's class header, I do import jni.h because the Objective-C class interacts with JNI directly.

Interfaces in Objective-C take the following form:

@interface ClassName : SomeSuperClass <ProtocolImplemented>
{
   variable declaration;
}
method declaration;
@end

Interfaces work differently in Objective-C than in Java. In Objective-C a declared interface is merely a declaration of one class. Although this use of interfaces exists in Java, it is not common. Objective-C uses what are called protocols, in addition to interfaces. Protocols more closely match the Java expectation and use of interfaces. Both Objective-C interfaces and Objective-C protocols together equate to Java interfaces.

Instead of surrounding interface declarations with curly braces as Java does, Objective-C surrounds interfaces with @interface and @end.

Interfaces defined with @interface do not extend other interfaces. (Remember, Objective-C @interfaces are class definitions.) Instead, @interfaces extend classes. In other words, Objective-C class extensions are handled by their class definitions—the interfaces. The colon (:) is used in place of the keyword extends that Java uses.

Class and object scoped methods and variables are defined in @interfaces. Objects and methods of class scope begin with a plus symbol (+). Objective-C's + is the equivalent of Java's static keyword. Methods and variables of object scope begin with a minus symbol (-). In the example code, the NativeLogExample contains one method named log of object scope.

The implementation of the NativeLogExample is in a file called NativeLogExample.m. The implementation for the Objective-C class NativeLogExample follows here:

#import "NativeLogExample.h"
// implementing the NativeLogExample class
@implementation NativeLogExample
// in Java this method signature would look like
// public void log (NSString message) { ... }
-( void ) log: (NSString *) message {

   // NSLog sends a log message to standard out
   // the message must be formatted. %@ is the
   // format specifier for objects. 'message' is
   // an object.
   NSLog( @"%@", message );

}
@end

The class implementation imports its own interface, and that is it. By convention, the file with the class implementation should import only one header: its interface. The interface takes care of all other imports.

Objective-C class implementations take the following form:

#import InterfaceDeclaration
@implementation ClassName
method implementations
@end

Notice that implementations start with the @implementation and end with the @end. Some programmers mix C-style functions into class implementations. I avoid this and instead place needed C-style functions into separate files that I then import into the class interface for use in the Objective-C class.

You can compile the C and Objective-C code using gcc directly if you like. The command for compiling the NativeLogExample and the nle.m file is something similar to the following:

gcc
         -bundle
         ./objc_src/nle.m
         ./objc_src/NativeLogExample.m
         -o ./objc_bin/libNativeLogger.jnilib
         -I/System/Library/Frameworks/JavaVM.framework/Headers
         -I ./objc_src/
         -framework JavaVM
         -framework Cocoa

The gcc command should be one line, not multiple lines. I formatted the gcc command for legibility.

The sample gcc command assumes that you have the headers and code in a subdirectory called objc_src. The command-line argument to create a dynamic library from the C and Objective-C is -bundle. Sometimes, I see -dynamic instead of -bundle; however, -dynamic can cause problems when loading multiple libraries for use with JNI. You are better off using -bundle to generate your dynamic library.

The argument -o specifies the name of the output file. The OS X convention for naming dynamic libraries in JNI is lib<name>.jnilib. The -I argument specifies directories of headers to search while building. The -framework argument specifies libraries used in the build. In this case, I use the JavaVM framework because the resulting library uses JNI. I also specify the Cocoa framework because I use an NSAutoreleasePool.

If you have followed the explanation of this first example up to this point, you have a fully workable Java-Objective-C application. It runs with the following command or one modified to match your classpath:

java -Djava.library.path=objc_bin -cp java_bin/ ¬
com.genedavis.NativeLogExample

The output is not too spectacular, but it is a good first step. Running your new JNI application results in output similar to the following:

2009-10-29 20:22:24.683 java[8280:d07] Hello world! (of course)

Setting up projects to handle javac, javah, and gcc is painful. If you want to move your project to a new IDE or share the project with a programmer using a different IDE, "painful" becomes horribly difficult. Set your build up with Ant or a similar build tool, and your project is more portable. Ant integrates with all Java IDEs. Best of all, Ant on OS X supports gcc through the exec tag, so even if your IDE does not officially support C or Objective-C, building the native code is no problem.

I set up an Ant build for this example in the project's build.xml file. The source for the Ant build.xml file follows:

<?xml version="1.0" encoding="UTF-8"?>
<project
      name="Native Log Example"
      default="run"
      basedir=".">
   <property name="java.source" value="java_src" />
   <property name="objective.c.source" value="objc_src" />
   <property name="java.bin" value="java_bin" />
   <property name="native.bin" value="objc_bin" />

   <target
      name="explain"

description="Explains the objective of the build">

      <echo>Building the full Java and Native source.</echo>

   </target>

   <target
      name="clean"
      description="Removes previous build">

      <echo>Cleaning Java and Native bin folders...</echo>

      <delete dir="${java.bin}" />
      <delete dir="${native.bin}" />

   </target>

   <target
      name="java-build"
    depends="clean"
      description="Builds the Java source">

      <echo>Building Java...</echo>

      <mkdir dir="${java.bin}"/>
      <javac srcdir="${java.source}" destdir="${java.bin}" />
   </target>

   <target
      name="native-header-build"
      description="Builds the native headers file">

      <echo>Creating native header file...</echo>

      <mkdir dir="${native.bin}"/>
      <javah
         outputfile="${objective.c.source}/native_log_example_jni.h"
         classpath="${java.bin}">

         <class name="com.genedavis.NativeLogExample" />

      </javah>
   </target>

   <target
      name="native-build"
      description="Builds the native lib*.jnilib">

<echo>Creating native lib*.jnilib</echo>

      <exec executable="gcc">

         <arg value="-bundle"/>

         <arg value="./${objective.c.source}/nle.m"/>
         <arg value="./${objective.c.source}/NativeLogExample.m"/>

         <arg line="-o ./${native.bin}/libNativeLogger.jnilib"/>
         <arg
value="-I/System/Library/Frameworks/JavaVM.framework/Headers"/>
         <arg line="-framework JavaVM"/>
         <arg line="-framework Cocoa"/>

      </exec>
   </target>

   <target
      name="build"
      depends="explain, java-build, native-header-build, native-build"
      description="builds full Java and Native byte code.">
      <echo>Build complete</echo>
   </target>

   <target
      name="run"
      depends="build"
      description="cleans, builds, and then runs app">
      <!--
      java
         -Djava.library.path=objc_bin
         -cp java_bin/
         com.genedavis.NativeLogExample
      -->
      <java
         classpath="${java.bin}/"
             classname="com.genedavis.NativeLogExample"
             fork="true">
             <jvmarg value="-Djava.library.path=${native.bin}" />
      </java>
   </target>
</project>

I discuss most of the Ant tasks used in this build.xml in Chapter 4. However, the javah and gcc integrations are new. The native-header-build target contains the task for javah execution. I chose the outputfile attribute instead of the destdir attribute. The outputfile attribute specifies a file in which to place all JNI headers. The destdir specifies a directory, and javah creates multiple header files in that directory. Typically, you use outputfile if you have few native methods to implement. Use destdir if your project has many native methods to implement.

Alternately, if you want better control over naming and destination directories for a project with many native methods, run the javah task several times to produce multiple header files with names and locations of your choice.

I run the gcc command inside of an exec task. Some commands run from inside exec need a full path specified. Because gcc is in the system path, simply executing gcc is enough. I pass the arguments to gcc in with the arg tag. Arguments that require two parameters use the line attribute. Arguments that require only one parameter use the value attribute.

When only building the application, use the command ant build from the Terminal. When building and running the application, use the command ant run from the Terminal. The result of executing ant run appears very similar to this output generated on my Mac:

Buildfile: build.xml
explain:
     [echo] Building the full Java and Native source.
clean:
     [echo] Cleaning Java and Native bin folders...
   [delete] Deleting directory /Users/tdavis/Desktop/ch08_code/
   native_log_example/java_bin
   [delete] Deleting directory /Users/tdavis/Desktop/ch08_code/
   native_log_example/objc_bin
java-build:
     [echo] Building Java...
    [mkdir] Created dir: /Users/tdavis/Desktop/ch08_code/native_
   log_example/java_bin
    [javac] Compiling 1 source file to /Users/tdavis/Desktop/
   ch08_code/native_log_example/java_bin
native-header-build:
     [echo] Creating native header file...
    [mkdir] Created dir: /Users/tdavis/Desktop/ch08_code/native_
   log_example/objc_bin
native-build:
     [echo] Creating native lib*.jnilib
build:
     [echo] Build complete
run:
     [java] 2009-10-26 20:42:48.029 java[3652:1303] Hello world!
   (of course)
BUILD SUCCESSFUL
Total time: 2 seconds

The line tagged run indicates the following output is the result of running the freshly built application. In this example, the output of run is:

[java] 2009-10-26 20:42:48.029 java[3652:1303] Hello world! (of course)

The only difference between this output and the output when running the java command yourself is that the output is prepended with [java]. The prefix [java] indicates that the line was generated from the java tool.

The CocoaComponent class belongs to the com.apple.eawt package. It is part of the Apple Java Extensions. The CocoaComponent is designed to wrap children of Objective-C's NSView class in such a way that they integrate with AWT. The CocoaComponent class is a child of java.awt.Canvas and behaves like any Canvas class.

To use CocoaComponent, extend it with your own class. Then add it to your own Java Container. In my example, I add it to a JFrame's content pane. Override the size methods to set the minimum, maximum, and preferred size of your CocoaComponent.

Sure, it sounds easy. After you look through the source of the example CocoaComponent child, I discuss the tricky bits.

The following is the source for the CocoaComponent child, CustomNSButton class:

package com.genedavis;
import java.awt.Dimension;
import javax.swing.JOptionPane;
import com.apple.eawt.CocoaComponent;
public class CustomNSButton extends CocoaComponent
{
   // executed during class load
   static
   {
      //used to load from a system library path
      System.loadLibrary("CustomNSButton");
      setupNativeCallbacks();
   }

   /**
    * Supersedes the createNSView() method.
    */
   public native long createNSViewLong();

   /**
    * Performing setup on the Native end.
    */
   public static native long setupNativeCallbacks();
   /**
    * This version of the createNSView() is
    * not used anymore, but you need to implement
    * it until it is removed from the API.
    */
   @Override
   public int createNSView() {
      return 0;
   }
   /**
    * Providing max size of NSButton.
    */
   @Override
   public Dimension getMaximumSize() {
      Dimension dim = new Dimension(150, 32);

return dim;
   }
   /**
    * Providing minimum size of NSButton.
    */
    @Override
   public Dimension getMinimumSize() {
      Dimension dim = new Dimension(150, 32);
      return dim;
   }
    /**
     * Providing preferred size of NSButton.
     */
   @Override
   public Dimension getPreferredSize() {
      Dimension dim = new Dimension(150, 32);
      return dim;
   }

   public void setCustomTitle(String title)
   {
      sendMessage(1, title);// 1 arbitrarily chosen
   }

   /**
    * Called from C. Do not call locally!
    *
    * Find the signature of this method in the
    * compiled class by calling:
    *
    * javap -private -s CustomNSButton
    *
    * from the command line.
    */
   @SuppressWarnings("unused")
   private void customButtonClicked()
   {
      // Remember that your system will lock up
      // if you don't give back the native thread
      // BEFORE trying to use Java AWT.

      Thread t = new Thread(new Runnable() {
         public void run()
         {
            JOptionPane.showMessageDialog(
                  null,
                  "You clicked the custom NSButton!");
         }
      });

      t.start();
   }
}

Four tasks in Java integrate CustomNSButton with its native counterpart:

static
{
   System.loadLibrary("CustomNSButton");
   setupNativeCallbacks();
}
public native long createNSViewLong();
public static native long setupNativeCallbacks();

The CocoaComponents wrap NSViews for use in Java GUI applications. Wrapping NSView opens up most, if not all, predefined and custom Cocoa widgets for use in AWT and Swing. To share the significance of the Java CocoaComponent, I explain the Objective-C NSView.

The Objective-C NSView class shares a similar position in the Cocoa framework as the java.awt.Component class shares in the Java API. Essentially, all widgets, buttons, tools, and panels in the Application Kit framework descend from NSView. NSView children include NSButton, NSTabView, NSOpenGLView, and NSColorWell. The NSView contains the largest tree in Cocoa's Application Kit (with the exception of its parent, NSResponder).

NSView handles events and basic drawing in Cocoa applications. NSViews are placed in NSWindows in similar fashion as Components are placed in JFrames and Windows in Java.

The online documentation for the Application Kit framework is located here: http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Intro/IntroAppKit.html.

As I have stated, CocoaComponents are wrappers for native NSViews. Using CocoaComponents, you can embed NSViews in Swing and AWT just like other java.awt.Components. Follow these steps:

No worries. After your CocoaComponent is written, the process for adding the NSView to Swing or AWT has no unusual steps.

The following code creates a JFrame and embeds a CocoaComponent in the JFrame:

package com.genedavis;
import java.awt.Container;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JOptionPane;
public class NSButtonExample {
   public static void main(String[] args)
   {
      // true prevents deadlock, but may cause JNI calls
      // to return asynchronously instead of synchronously.
      System.setProperty(
            "com.apple.eawt.CocoaComponent.CompatibilityMode",
            "false");

      new NSButtonExample();
   }

   public NSButtonExample()
   {

      final JFrame mainFrame =
         new JFrame("Custom NSButton Example");
      Container pane = mainFrame.getContentPane();
      pane.setLayout( null );

      CustomNSButton button = new CustomNSButton();
      mainFrame.add( button );

      button.setSize( button.getPreferredSize() );
      button.setLocation(120,70);

      mainFrame.setSize(400, 200);
      mainFrame.setVisible(true);

      // cannot call until the button is visible
      // or a null pointer exception occurs.
      button.setCustomTitle("Custom NSButton");

   }
}

These steps allow you to use the custom CocoaComponent in this code example:

JavaVM pointers represent an entire JVM. JavaVM pointers are most commonly used in creating JVMs from native code. In the case of using CocoaComponent, I don't create a JVM from native code. Instead, I grab a reference to the JVM for use in handling user-generated events that need callbacks to Java.

The best way to grab a pointer to the JVM in a native library is when the JVM loads the native library. When loading a JNI-based dynamic library, Java calls the JNI_OnLoad() function. The first argument to JNI_OnLoad() is a JavaVM pointer.

For quick reference, here again is the code for the JNI_OnLoad() function in nbe.m:

JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
{
   jvm = vm;
   return JNI_VERSION_1_6;
}

The JavaVM pointer is good for as long as the JavaVM exists. Unless you are creating and destroying JVMs from native code, JavaVM points won't go bad. So I grab the pointer during the onload call and keep it in a static variable for future use.

As you probably can guess, jobjects represent Java class instances. There are three types of jobject pointers: local, global, and weak global references. Local references go out of scope and clean up as soon as a native call returns to the JVM. Both types of global references remain valid after the native method call returns. Both types of global references are candidates for caching.

I choose to cache a global reference in the nbe.m example instead of a weak global reference. The difference between weak global and standard global jobject references is that weak global references allow for the underlying object to be garbage collected. I have no need for garbage collecting the referenced object. Normally, the choice between weak and standard jobject references comes down to whether the Java Object is consuming many resources.

I create the jobject reference in nbe.m, in this function:

Java_com_genedavis_CustomNSButton_createNSViewLong()

Here is the full source for the native createNSViewLong() function:

JNIEXPORT jlong JNICALL
Java_com_genedavis_CustomNSButton_createNSViewLong
(JNIEnv * env, jobject jobj)
{
   customNSButtonJavaObject =
     (*env)->NewGlobalRef(env, jobj);

   NSAutoreleasePool  *pool = [[NSAutoreleasePool alloc] init];

   NSButtonExample *customButton = nil;
   customButton = [[NSButtonExample alloc] init];

   [pool release];

return (long)(uintptr_t) customButton;
}

The call to (*env)->NewGlobalRef(env, jobj) actually created the global jobject reference. I store the global reference in the static variable customNSButtonJavaObject.

Object references are stored in jobject pointers. So it is no surprise that method references are stored in jmethod pointers. References to methods stay good between native calls. Caching jmethod pointers is perfectly safe if the JVM itself won't go away.

Remember the static block in CustomNSButton. In the static block, I call setupNativeCallbacks(). In the native implementation of that method, I grab the jmethod reference. In fact, that is the only operation performed in the native implementation.

Here again is the source for quick reference:

JNIEXPORT jlong JNICALL
Java_com_genedavis_CustomNSButton_setupNativeCallbacks
(JNIEnv *env, jclass jclazz)
{
   buttonClickMethod =
      (*env)->GetMethodID(
                       env,
                       jclazz,
                       "customButtonClicked",
                       "()V");
}

The function call GetMethodID() retrieves the jmethod pointer, buttonClickMethod. The GetMethodID() function takes the JNIEnv pointer, a jclass pointer, the name of the method, and a signature for the method. The native method call provides both the JNIEnv pointer and the jclass pointer. Just use the variables passed in on the method call. The method name, in this case "customButtonClicked", is just the name of the Java method.

The method signature needs a little more discussion. Potential method overloading in Java creates the need for distinguishing methods with similar names but different signatures. The format for a method signature is as follows:

(<argument><argument><...>)<return>

Methods with no arguments contain an empty set of parentheses. Methods with no return value ends with a V. In the case of the method customButtonClicked(), the signature is "()V". Retrieve more complex method signatures with the javap tool.

The command for obtaining all the method signatures in CustomNSButton is this:

javap -s -private CustomNSButton

To run javap against your own class, just change the name of the class in the javap command to the name of your class. Run the javap tool against the compiled CustomNSButton class, and it returns the following results:

public class com.genedavis.CustomNSButton extends com.apple.eawt.
   CocoaComponent{
public com.genedavis.CustomNSButton();
  Signature: ()V
public native long createNSViewLong();
  Signature: ()J
public static native long setupNativeCallbacks();
  Signature: ()J
public int createNSView();
  Signature: ()I
public java.awt.Dimension getMaximumSize();
  Signature: ()Ljava/awt/Dimension;
public java.awt.Dimension getMinimumSize();
  Signature: ()Ljava/awt/Dimension;
public java.awt.Dimension getPreferredSize();
  Signature: ()Ljava/awt/Dimension;
public void setCustomTitle(java.lang.String);
  Signature: (Ljava/lang/String;)V
private void customButtonClicked();
  Signature: ()V
static {};
  Signature: ()V
}

Each method signature is clearly stated. Just copy the results to the GetMethodID when retrieving jmethod references.

JNIEnv references provide the means for calling most of the methods you need when handling JNI native method implementations. You will get very accustomed to typing the following:

(*env)->SomeMethodNames();

The pointers I discussed so far are valid between native calls. JNIEnv is not valid across threads. Never cache JNIEnv pointers.

JNIEnv pointers are the first argument to all methods in JNI, so getting a new one that is valid on your current thread is usually not difficult when the thread is provided by the JVM. However, when you handle threads generated by user events on an NSView, you need to get your own JNIEnv pointer.

The notifyJavaThatButtonWasClicked( void ) function in nbe.m provides an example of obtaining a JNIEnv pointer from a JavaVM pointer. For convenience, the source for notifyJavaThatButtonWasClicked( void ) follows:

void notifyJavaThatButtonWasClicked( void )
{

   JNIEnv *env = NULL;
   jint env_error = JNI_OK;
   BOOL detach = NO;

   env_error = (*jvm)->GetEnv(
                              jvm,
                              (void **)&env,
                              JNI_VERSION_1_6);

   if ( env_error == JNI_EDETACHED)
   {
      // Attaching this thread to a JVM thread
      env_error = (*jvm)->AttachCurrentThread(
                                              jvm,
                                              (void **)env,
                                              NULL);

      if (env_error == JNI_OK)
      {
             detach = YES;
      }
   }

   (*env)->CallVoidMethod(
                          env,
                          customNSButtonJavaObject,
                          buttonClickMethod);

if (detach)
   {
      (*jvm)->DetachCurrentThread( jvm );
   }
}

Follow these steps to obtain a JNIEnv pointer:

Finally, all this work getting a valid JNIEnv allows you to perform a callback using the CallMethod(). The actual call in nbe.m follows:

(*env)->CallVoidMethod(
                          env,
                          customNSButtonJavaObject,
                          buttonClickMethod);

The word "void" in the CallVoidMethod() function indicates that the return value of the method you are calling is void. If there are arguments to the method, pass the appropriate JNI variables in to the function call as additional argument to the function call.