Next: 4.2 The GNUmakefile for Up: 4. Wrapping Objective-C Libraries Previous: 4. Wrapping Objective-C Libraries

Subsections

- 4.1.1 Creating and compiling the wrappers
- 4.1.2 Structure of the wrappers
  - 4.1.2.1 The Java subdirectory
  - 4.1.2.2 The Objc subdirectory

# 4.1 Compiling ready-to-use wrappers

We start by reviewing the simplest case: you have a library installed on your system, and you download the wrappers for that library. The wrappers actually consist of a `GNUmakefile`, a `.jigs` file, and possibly a few other support files. These files contain all the instructions JIGS needs to wrap your library. You can try the discussion out by using any example in the `Tools/WrapCreator/Examples/` directory (which are slightly more complicated, as the library and the wrapper for the library are kept and compiled in the same directory at the same time).

## 4.1.1 Creating and compiling the wrappers

When you type `make`, JIGS will automatically create a directory called

    JavaWrapper

and generate inside this directory source code for the wrappers. It will then enter into this directory, and compile the wrapper source code (which has just been generated). If you want more details about the wrapping process (which classes and which methods are being wrapped), you can use

    make verbose=yes

To access your library from Java you need to have compiled and installed both the original library and the wrappers.

Typing `make install` will install the wrappers, so you should be ready to use them from Java.

##
4.1.2 Structure of the wrappers

It's not strictly necessary for you to know the structure of the wrappers to create or use them, so you may safely skip this section.

In the following discussion, we consider wrappers for an imaginary library called `libexample.so`.

The wrappers for the library are composed of two parts: a set of Java classes, and a native Objective-C library, called `libexample.A.so` in the example. This is called after the original library (`libexample.so`) with a `.A` appended to the name.

If you go into the `JavaWrapper` directory, you can inspect these parts yourself. There are two main subdirectories in the `JavaWrapper` directory, the `Java` and the `Objc` subdirectories.

### 4.1.2.1 The Java subdirectory

The `Java` subdirectory contains the Java classes. All methods which are not explicitly marked as `public` in these classes are to be considered internal to the JIGS engine and you should not access them directly (you probably will not be allowed to anyway).

All these classes contain a static initializer of the following form:

     static
      {
        JIGS.loadLibrary ("example.A");
      }

This will load the native library `libexample.A.so` as soon as the first Java class is accessed (`libexample.A.so` will implicitly load `libexample.so`).

Then, most methods are `native`, as in the following example:

     /**
       * Wraps the Objective-C method
       * <B>start</B>
       */
      public native void start ();

The implementation of the Java methods marked as `native` will be found by the JVM inside the native library `libexample.A.so` (see next section).

As it is shown in the example, each class and public method has a tiny minimal javadoc description. When the java classes are compiled, quick reference documentation for the classes will be generated from these comments by using javadoc, and put into the subdirectory `Reference`. This documentation is minimal, and basically consists in the list of all Java wrapper classes and methods which were compiled, and for each one, a comment explaining which Objective-C class or method it wraps. While minimal, this documentation can be quite useful for someone already knowing the Objective-C API (or having the Objective-C documentation to refer to) and wanting to use the library from Java.

### 4.1.2.2 The Objc subdirectory

The `Objc` subdirectory contains the Objective-C library `libexample.A.so`, which provides to Java the implementation of all the `native` methods in the Java classes. The implementation of these methods will call the corresponding methods in the (pure Objective-C) `libexample.so` library, by using the JIGS core engine to catch exceptions, convert arguments and return types, etc.

Next: 4.2 The GNUmakefile for Up: 4. Wrapping Objective-C Libraries Previous: 4. Wrapping Objective-C Libraries