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).
When you type make, JIGS will automatically create a directory called
JavaWrapper(or JavaWrapper_debug if you are compiling with debug enabled), 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.
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.
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.
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.