Tutorial

Features

Here, an example will explain more than a documentation.

Complete example:
All the files are available in the GIWS distribution in the directory examples/basic_example/
Imagine that you have a very complex Java class which takes two doubles and is doing very complex computation on it.

First step:

Create my java class Example: _basic_example/MyComplexClass.java_

package basic_example;

import java.lang.Math;

public class MyComplexClass{

    public MyComplexClass(){
        // the constructor
    }

    public long myVeryComplexComputation(double a, double b){
        return Math.round(Math.cos(a)+Math.sin(b)*9);
    }
}

Second step (optional):

Check that your class is working.
Example: _basic_example/UseCase.java_

package basic_example;

public class UseCase {
    public static void main(String[] args){
        MyComplexClass testOfMyClass = new MyComplexClass();
        System.out.println("My Computation : " +testOfMyClass.myVeryComplexComputation(1.2,80));
    }
}

This should give : # javac basic_example/*.java # java basic_example.UseCase My Computation : -9

Third step:

Create the GIWS declaration file.

Example: MyComplexClass.giws.xml
The XML is pretty straightforward:

<package name="basic_example">
  <object name="MyComplexClass">
        <method name="myVeryComplexComputation" returnType="long">
          <param type="double" name="a" />
          <param type="double" name="b" />
        </method>
  </object>
</package>

Fourth step:

Launch the code generation.

# /pathToGiws/giws.py -f MyComplexClass.giws.xml
MyComplexClass.hxx generated ...
MyComplexClass.cpp generated ...

GIWS is generating the class declaration and implementation. These files are managing JNI calls, convertion of the data/objects...

Fifth step:

Create the C++ code which will call the GIWS class.

The function create_vm is not taken in charge by GIWS since there is many ways and many needs to do it... Maybe GIWS will take this in charge in the future.
Example: main.cpp #include #include "MyComplexClass.hxx" #include <jni.h> JavaVM* create_vm() { JavaVM* jvm; JNIEnv* env;

    JavaVMInitArgs args;
    JavaVMOption options[2];

    /* There is a new JNI_VERSION_1_4, but it doesn't add anything for the purposes of our example. */
    args.version = JNI_VERSION_1_4;

    args.nOptions = 2;
    options[0].optionString = "-Djava.class.path=.";

    options[1].optionString = "-Xcheck:jni";
    args.options = options;

    args.ignoreUnrecognized = JNI_FALSE;

    JNI_CreateJavaVM(&jvm, (void **)&env, &args);

    return jvm;
}

using namespace basic_example;
using namespace std;

int main(){
    JavaVM* jvm = create_vm();

    MyComplexClass *testOfMyClass = new MyComplexClass(jvm);
    cout << "My Computation : "  << testOfMyClass->myVeryComplexComputation(1.2,80) << endl;

    return 0;	
}

Sixth step:

Compile all the files:
It is mandatory that you declare the variable JAVA_HOME since you will need header files and the native Java libraries (you may have to change the path to match your configuration).

# export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun
# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/client/
# g++ main.cpp MyComplexClass.cpp -g -o myExample  -ljvm -I$JAVA_HOME/include -I$JAVA_HOME/include/linux -L$JAVA_HOME/jre/lib/i386 -L$JAVA_HOME/jre/lib/i386/client/

Seventh step:

Test it:

# ./myExample
My Computation: -9

Here we are !

Limitations

There are a few limitations on the use of GIWS :

• It is not possible to use custom Java objects yet.
• The constructor has to be empty (this will change in the future). A trick to avoid this limitation is to create a Java class with setter to initialize everything.