Caffeine.berlios.de

Caffeine Quickstart Guide
by Bruno Fernandez-Ruiz
Table of contents
1. Introduction
Caffeine is an interoperability solution between the .NET and the Java platform. At the coreof Caffeine is JNI.NET, a set of bindings of the Java Native Interface (JNI) for the .NETplatform. .NET applications using JNI.NET can instantiate and invoke methods on any Javaclass.
JNI is a complex and error prone technology, and although JNI.NET hides most of thecomplexity in JNI, it is still somehow hard and unconvenient to program directly against it.
Using JNI.NET to manually create 1:1 mappings of a Java library is a very repetitive process,obviously a great candidate for automation. This is exactly what the generators in JNI.NETdo: they automatically generate C# wrapper classes that use JNI.NET to access Java classes.
Most .NET developers will never need to access the JNI.NET API directly - instead they willjust use the automatically generated C# wrapper classes like they would use a Java library.
This guide provides a quick overview of the generators contained in JNI.NET, which assistdevelopers in the process of creating .NET assemblies from Java libraries. If you areimpatient about using Caffeine, you should at least read this guide. If you want to understandhow JNI.NET works, why the generated code looks like it does, and how to access directlythe JNI.NET API, for specialized tasks that the generated code does not cover, you shouldread the 2. Your first cup of Caffeine
In order to understand how to use the generators, we will go through a simple example of Copyright 2004 The Olympum Group. All rights reserved. how to generate .NET wrapper classes of a nice little library called "jcool.jar". For yourreference, "caffeine/jni.net/examples/generators".
You have been working with "jcool.jar" for quite a while now, and you are really familiarwith the JCool library. While creating a new .NET application, you realize that it would berather useful to get access to the JCool library features directly, instead of having to rewritethe same functionality in C# or VB.NET. This is why you approach JNI.NET. The end resultof the JNI.NET generator tool chain is a .NET assembly that will interoperate with the"jcool.jar" library under the hood, and will allow you to write .NET applications that use theJCool library, like you were using the Java library directly.
The JNI.NET generator tool chain starts with the "JavaApiXmlGenerator". What thisgenerator does it to load a jar file, and generate an Xml descriptor file containing all classes,methods and fields contained in the given jar file. This Xml file can then be processed by theC# JNI.NET wrapper generator ("CsJniNetWrapperGenerator"), which will create C# sourcefiles that interoperate with the jcool.jar library via JNI.NET. The JNI.NET bindings arecontained in the assembly Caffeine.Jni.dll.
We would start by generating "jcool.xml", which is the Xml description of the classes,methods and fields contained in "jcool.jar": [win32] java -classpath "generators.jar;dom4j.jar" \ com.olympum.tools.JavaApiXmlGenerator jcool.jar jcool.xml [linux] java -classpath "generators.jar:dom4j.jar" \ com.olympum.tools.JavaApiXmlGenerator jcool.jar jcool.xml The classpath must contain at least the "generators.jar" (from JNI.NET) and "dom4j.jar", plus possibly all the Java libraries onwhich "jcool.jar" depends upon publicaly (in this example, we assume that jcool.jar does not depend on any external library atthe interface level).
Once we have "jcool.xml", we can generate the C# source wrapper code: [win32] java -classpath generators.jar;dom4j.jar \ com.olympum.tools.CsJniNetWrapperGenerator jcool.xml src [linux] java -classpath generators.jar:dom4j.jar \ com.olympum.tools.CsJniNetWrapperGenerator jcool.xml src This will generate C# classes under the directory src for all types described in jcool.xml.
Please notice that only wrapper C# classes are only generated for the public and protectedAPI.
Copyright 2004 The Olympum Group. All rights reserved. Alternatively, since Caffeine 0.2, you can use the provided 'caffeinator' script to go directly from your jar file to the generatedC# source files.
You can now compile the source under the src directory to create the jcool.dll: [.NET] csc /t:library /r:Caffeine.Jni.dll /r:javart.dll \ [Mono] mcs /t:library /r:Caffeine.Jni.dll /r:javart.dll \ "javart.dll" is an automatically generated assembly containing the Java runtime (rt.jar). InCaffeine 0.1, it only contains the classes necessary to compile java.lang.Object, plus a fewextra others. As an interesting point, note that the "javart.dll" library itself is generated thesame way as "jcool.dll". In Caffeine 0.1, the support for Java applications is limited to thetypes contained in javart.dll.
The reason for the limited-version of "javart.dll" is because Caffeine 0.1 is unable at this point to compile the full Java runtime.
We expect to be able to remove this limitation soon.
The generated "jcool.dll" assembly contains C# types equivalent to the public and protectedJava API of "jcool.jar". Your .NET applications can now use the JCool library as they wouldin Java. For example, you could write a C# class TestAbstract.cs: Template t = Template.getInstance ();t.foo (t); This example shows how the Java type "com.acme.jcool.Template" is accessed from .NET.
[.NET] csc /r:javart.dll /r:jcool.dll TestAbstract.cs[.NET] mcs /r:javart.dll /r:jcool.dll TestAbstract.cs will generate TestAbstract.exe, a .NET executable assembly using the "jcool.jar" library.
Copyright 2004 The Olympum Group. All rights reserved. 3. Running an application using JNI.NET
Once TestAbstract.exe has been generated, you can run it. You need to make sure howeverthat: "Caffeine.Jni.dll", "javart.dll" and "jcool.dll" are present either in the directory where"TestAbstract.exe" resides, or in the GAC.
jninet.dll (or libjninet.so) is present somewhere in your PATH (for win32 platforms) oron your LD_LIBRARY_PATH (for Un*x/Linux).
If your Java runtime library (jvm.dll or libjvm.so generally) is not on the PATH (onWindows) or on your LD_LIBRARY_PATH (on Un*x/Linux), or if the Java runtime isnot called jvm.dll or libjvm.so, you will need to configure Caffeine (see next section).
You have specified a CLASSPATH environment variable so that "jcool.jar" is available;alternatively you can configure the CLASSPATH in Caffeine (see next section).
If the JCool library uses native calls, you must specify in the Caffeine configuration thepath were the Java runtime should look for native libraries (see next section).
4. Configuring Caffeine
Caffeine provides a configuration mechanism that allows you to specify the library load path,the classpath, and the command line arguments you would like to pass to the Java runtime.
This is especially interesting when either you have to setup a complex CLASSPATH (usuallythe case in J2EE applications), or because your JVM is not called jvm.dll or libjvm.so.
In order to configure TestAbstract.exe, you would create a TestAbstract.exe.config file,residing on the same directory as TestAbstract.exe. The contents of TestAbstract.exe.configcould be like: <?xml version="1.0" encoding="utf-8" ?><configuration> <sectionGroup name="caffeine"><section name="jni.net"type="Caffeine.Jni.JNISectionHandler,Caffeine.Jni"/></sectionGroup> </configSections><appSettings></appSettings><caffeine> <jvm.dll value="libjvmi.so"/> Copyright 2004 The Olympum Group. All rights reserved. <java.class.path value="jcool.jar"/><java.class.path value="xerces.jar"/><java.library.path value="/opt/web/lib"/><java.option value="-verbose:gc,class"/> In this example, we are specifying that the JVM is contained in a DLL called libjvmi.so(which must be available in either the PATH on win32, or on the currentLD_LIBRARY_PATH on Un*x/Linux); that the classpath should contain the "jcool.jar" and"xerces.jar" files (in current directory since no relative nor absolute path is given in thisexample); that native libraries (e.g. System.loadLibrary()) should be looked from/opt/web/lib, and that class garbage collection should be traced at verbose level.
Copyright 2004 The Olympum Group. All rights reserved.

Source: http://caffeine.berlios.de/site/documentation/quickstart.pdf