This sample is located in \Samples\Com\CustomMarshal\Template.
Note To use this sample, it is recommended that you have Microsoft® Visual C++® version 5.0 or higher installed.
Description
Using the Sample
Technologies Demonstrated
This sample shows how to use hook classes. TemplateMarshaler.def contains C functions for eight hook methods. The comments inside each function describe what that hook function does. Details are provided in the other custom marshaling examples.
Note the following information about hook functions:
Important All pointers passed to hook methods are double-indirect ETYPE (PPETYPE). For many methods (such as releaseExternal), this will seem like an unnecessary level of indirection. The reason ETYPE is always double-indirected has to do with an obscure feature of hook classes that allows you to redefine the size and nature of a pointer to ETYPE.
Custom marshaling, except for the extra step of writing a hook class and listing your data types in the .jnf file, is the same as integrating any other COM library with Java.
A hook class is a collection of static methods and fields packaged as a Java class. The hook class must be installed and visible to the class path on any system where the user-defined types are used. Otherwise, hook classes remain mostly hidden. The Microsoft VM loads the hook class as part of loading a jactivex-created interface file that references the user-defined types, and invokes methods on the hook class to marshal them.
The Java/COM integration layer of the Microsoft VM never creates an instance of a hook class. There are around 10 fields and methods recognized as hook class members. They are all either optional or have reasonable defaults, so most hook classes need to implement only a subset of the members.
A hook class has the following responsibilities:
In turn, the Microsoft VM is responsible for calling the appropriate hook methods at the right time whenever ETYPEs are passed to or from COM methods. Once the hook class is written, the VM automatically supports passing ETYPEs (if it is fixed-size), ETYPE*, and ETYPE**, as well as returning ETYPE*. The VM also implements the correct semantics for [in], [out], [in,out], and [out,retval] type library attributes, which jactivex passes along using the extra bits in the .class file. An [out] attribute or double indirection is mapped to a one-element array of JTYPE rather than to JTYPE itself.
Although hook classes are packaged as Java classes, they cannot be written in Java. Hook classes must receive and pass memory addresses (pointers). Java methods can receive pointers as integers, but Java cannot dereference, allocate, destroy, or otherwise manipulate pointers. Therefore, use RNI to write hook classes. RNI allows Java methods to be implemented as C functions inside a DLL. RNI also offers a small set of APIs that can be called from C to create, manipulate, and destroy Java objects.
To install the sample
Copy the following files from \Samples\Com\CustomMarshal\template to a new directory:
To compile the sample
Follow the instructions in each of the comments marked TODO in TemplateMarshaler.java and TemplateMarshaler.c. This involves replacing ETYPE and JTYPE with your particular type, and uncommenting some optional methods.