Template Custom Marshaling Sample

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

Description

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.

Additional Information

Note the following information about hook functions:

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:

  1. Specifying the Java type (generically referred to as JTYPE). JTYPE can be a primitive type (int, double, and so on) or a reference type (objects and arrays).

  2. Specifying the size (in bytes) of the COM type (generically referred to as ETYPE). ETYPE can be variably sized. If it is, the hook class indicates this by not offering a size.

  3. Providing code (methods) to translate JTYPEs to ETYPEs and back.

  4. Optional: Providing destructor code for ETYPEs to release embedded resources.

  5. Optional: Providing code to allocate and free ETYPEs.

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.

Using the Sample

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.

Technologies Demonstrated

Custom Marshaling

© 1999 Microsoft Corporation. All rights reserved. Terms of use.