com.apple.mrj.jdirect
Class Linker

java.lang.Object
  |
  +--com.apple.mrj.internal.jdirect.Linkage
        |
        +--com.apple.mrj.jdirect.Linker

public class Linker

extends com.apple.mrj.internal.jdirect.Linkage

Linker is a factory class for producing Objects which JDirect 3 use to bind native methods to native code.

A class that has native methods that are to be called via JDirect 3 must have a static Object field which is initialized via new Linker(Class) For example:

		interface FooLibrary {
			public static final String JDirect_MacOSX  = "/System/Foo.dylib";
			public static final String JDirect_MacOS   = "FooLib";
			public static final String JDirect_Windows = "FOO.DLL";
 		}
		class FooFunctions implements FooLibrary
			static Object linkage = new Linker(FooFunctions.class);

			static native int FooInit();
			static native int NewFoo();
		}
	

The creation of the Linker object allocates and registers JNI glue code for all native methods in the class. The JNI glue code thunks restructure parameters from JNI style to JDirect style and call through to the function exported by a shared library. When the linkage object that is returned is GC'ed the JNI native methods are unregistered and deallocated.

During the creation of the Linker object, reflection is used to find all strings with the name JDirect_platform in the target class, its superclasses, or interfaces it implements. Those strings make an ordered list of libraries to search for functions which match the name of each native method. Currently, the namespace for JDirect_ strings is:

		JDirect_MacOSX	-> Mac OS X
		JDirect_MacOS	-> MRJ 2.x (not shipping)
		JDirect_Windows	-> Windows 9x/NT (not implemented)
		JDirect_Linux	-> Linux (not implemented)
	

The following table is used by JDirect 3 to convert java parameter types to C parameter types:

           Java     C
           boolean    unsigned char  (0x00 for false and 0x01 for true)
           byte       signed char
           char       unsigned short
           short      signed short
           int        signed long
           long       signed long long
           float      float
           double     double
           byte []    char*          (pointer to first element of array)
           short []   short*         (pointer to first element of array)
           int []     long*          (pointer to first element of array)
           long []    long long*     (pointer to first element of array)
           all other parameter types are unsupported.
	

The following table is used by JDirect 3 to convert java return types from C return types:

           Java     C
           void       void
           boolean    unsigned char  ( b != 0 )
           byte       signed char
           char       unsigned short
           short      signed short
           int        signed long
           long       signed long long
           float      float
           double     double
           all other return types are unsupported.
	

Field Summary

static boolean	DONT_MAINTAIN_CARBONLOCK
static boolean	MAINTAIN_CARBONLOCK
static boolean	verbose If verbose is set to true, then JDirect will log to stderr progress information about JDirect.

Constructor Summary

Linker()
A alternate constructor for subclasses of Linker.

Linker(boolean lockAroundCalls)

Linker(Class targetClass)
This method is used to link a class's native methods.

Linker(Class targetClass, boolean lockAroundCalls)

Method Summary

protected static boolean

initialVerbosity() Initializes JDirect verbose to true if: System Property jdirect.verbose is defined, or Shell variable JDIRECT_VERBOSE is defined

Methods inherited from class com.apple.mrj.internal.jdirect.Linkage

finalize, getPlaformLinker, shellVariableDefined

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAINTAIN_CARBONLOCK

public static final boolean MAINTAIN_CARBONLOCK

DONT_MAINTAIN_CARBONLOCK

public static final boolean DONT_MAINTAIN_CARBONLOCK

verbose

public static boolean verbose

If verbose is set to true, then JDirect will log to stderr progress information about JDirect. You may find it useful when debugging code which uses JDirect.
It can be set programmitically by assigning to this variable. Its initial value is true if the shell variable JDIRECT_VERBOSE is defined or the System property jdirect.verbose contains true.

Since:

JDirect 3

Constructor Detail

Linker

public Linker(Class targetClass)

This method is used to link a class's native methods. For example:

		class FooFunctions {
			static Object linkage = new Linker(FooFunctions.class);

			static native int FooInit();
			static native int NewFoo();
		}
	

IMPORTANT: It must be called from the initializer of a static field in the class.
This method will search the specified library for exported functions that have the same name as native methods. It will allocate thunks and register them as JNI native methods. The thunks will marshall the JNI parameters into JDirect parameters and call into the function exported from the library.

Since:

JDirect 3

Linker

public Linker(Class targetClass,
              boolean lockAroundCalls)

Linker

public Linker()

A alternate constructor for subclasses of Linker. The targetClass is the subclass itself. This style is useful in that in avoids the code bloat in client classes caused by the use of the MyClass.class construct.

		class BarFunctions extends Linker {
			static Object linkage = new BarFunctions();

			static native int BarInit();
			static native int NewBar();
		}
	

The above will link the native methods in BarFunctions. IMPORTANT: You should only subclass Linker if your class design requires no object instantiations. That is you have only static methods and variables. Otherwise JDirect will re-link the native methods each time one of your objects is instantiated.
IMPORTANT: It must be called from the initializer of a static field in the class.

Since:

JDirect 3

Linker

public Linker(boolean lockAroundCalls)

Method Detail

initialVerbosity

protected static boolean initialVerbosity()

Initializes JDirect verbose to true if: System Property jdirect.verbose is defined, or Shell variable JDIRECT_VERBOSE is defined

Since:

JDirect 3