A Word on the JavaCOM Language Mapping

---

A Word on the Java/COM Language Mapping

J++ is Microsoft's Java IDE. Although you can create 100% pure Java code with J++, you will discover just by tinkering with the tool for a bit that it is (a) very Windows-centric and (b) has great support for COM technologies. To date, Visual J++ is the only Java IDE that supports COM development.

Not all Java Virtual Machines (JVM) support a COM to Java language mapping. Microsoft's JVM is the only virtual machine capable of working with the Java/COM language mapping. Keep in mind that when you choose to integrate COM and Java, you are losing Java's platform independence and become tied to the Microsoft Java interpreter.

Note 

When you create any "unpure" Java solution with J++, you will be prompted with a few dialog boxes asking for your permission to import the necessary Java packages that will tie you to the Windows OS. Say "OK" and you are ready to go.

Including Your Type Information into a J++ Project Solution

Much like a VB client, a Java client must include the type information for the COM server it wishes to program against, using the COM Wrappers dialog box. You may include type information using the Project | Add COM Wrapper menu selection of the J++ IDE:

Figure 4-10: J++ COM Wrappers dialog box.

Once you select the desired *.tlb file, you will have a new Java package added to your current J++ solution space which contains all the interfaces, coclasses, and other COM definitions found in the type information, each of which is placed in a separate *.java file. These files contain Java to COM proxy wrappers, which map Java source code to various COM library calls. The bridge between the two is your friendly MS Java Virtual Machine. From the Project Explorer, you can see the contents of the shapes package:

Figure 4-11: IDL constructs end up as Java proxy classes.

Again, much like Visual Basic, you may use the Java Object Browser (F2, provided you have a *.java file as the active window) to examine the type information of the COM server:

Figure 4-12: The Java Object Browser.

Examining the Generated Java Code

When you include type information using the COM Wrappers utility, you trigger a utility named jactivex.exe which engineers IDL types into corresponding Java classes. As things turn out, these classes are proxies to the real binary COM objects. Let's walk through the files brought in by jactivex.exe for the shapes project.

The FILLTYPE enumeration is realized in Java as a collection of "static final" types (Java has no enum keyword). Here is the content of the FILLTYPE.java file:

// The IDL enumeration is mapped to a collection of constant types. public interface FILLTYPE {      public static final int HATCH = 0;      public static final int SOLID = 1;      public static final int POLKADOT = 2; }

How about the custom interfaces? J++ makes use of a specific package (com.ms.com) to provide the necessary COM support. Jactivex.exe embeds the IID of the interface as a static final data member as part of the class definition (omitted for clarity). Here is our Java savvy IDraw interface (IShapeEdit appears similar):

// IDraw in Java. public interface IDraw extends IUnknown {      public void Draw(); }

Next, we have the CoHexagon coclass itself. This is a creatable Java class which implements the IUnknown, IDraw, and IShapeEdit interfaces. All the method names come through as native, reminding us that we are developing an unpure Java solution:

// The J++ developer will create an instance of CoHexagon in the Java source code. // Note the use of the Java 'implements' keyword. public class CoHexagon implements IUnknown,                             com.ms.com.NoAutoScripting,                             shapes.IDraw,                             shapes.IShapeEdit {      public native void Draw();      public native void Fill(int fType);      public native void Inverse();      public native void Stretch(int factor); }

The support for the NoAutoScripting interface marks this coclass as a non-automation based class (i.e., no support for IDispatch) accessible through the coclass vTable only. As the J++ developer, you can ignore the NoAutoScripting interface and just concentrate on creating a CoHexagon and accessing the IDraw and IShapeEdit interfaces. Before we see the Java code to do just this, here is some further information on the Java to COM mapping layer.

Getting @com in Java

When you examine the jactivex.exe generated code, you will find a number of source code comments using the @com prefix. These prelimiters are directives used by the MS JVM to map Java atoms to COM atoms during runtime (therefore don't remove these comments). Here is a breakdown of the most common MS JVM directives:

J++ COM Directive	Meaning in Life
@com.class	Specifies that this Java class maps to a COM coclass.
@com.interface	Marks a COM interface, including the GUID used to represent it.
@com.method	Used with @com.parameters to map universal COM types to Java types. Also marks the vTable offset for each method.
@com.struct	Maps a COM structure to a Java class (Java has no struct keyword).

Full commentary on the @com directives can be obtained from online help (MS Developer Network) under the Java/COM Attributes Reference section. Armed with this information, let's examine how JActivex.exe really defined IDraw:

// VTable-only interface IDraw /** @com.interface(iid=4B475690-DE06-11D2-AAF4-00A0C9312D57, thread=AUTO) */ public interface IDraw extends IUnknown {      /** @com.method(vtoffset=0, addFlagsVtable=4)          @com.parameters() */      public void Draw(); public static final com.ms.com._Guid iid = new com.ms.com._Guid((int)0x4b475690,  (short)0xde06, (short)0x11d2, (byte)0xaa, (byte)0xf4, (byte)0x0, (byte)0xa0, (byte)0xc9,  (byte)0x31, (byte)0x2d, (byte)0x57); }

Creating Coclasses and Accessing Interfaces from Java

The Java/COM language mapping is about as seamless as you can get. All calls to the COM library are hidden deep within COM-specific packages and MS JVM. To create an instance of your coclass, use the Java new operator. This will call CoCreateInstance() on your behalf. When you wish to obtain a given interface from the coclass, you perform an explicit Java style cast (which looks very much like a C++ style cast).

Assume you have created a new J++ Windows Application workspace, and have included the correct COM wrapper. Here is a Java class named ShapesConsumer making use of CoHexagon:

// Some Java code making use of CoHexagon. import shapes.*;          // Must import files into a class referencing them. public class ShapesConsumer {      // Create private member variables for the coclass & interfaces.      private shapes.CoHexagon myHex;      private shapes.IDraw itfDraw;      private shapes.IShapeEdit itfSE;      public static void main(String[] args)      {           // Make the CoHexagon           myHex = new shapes.CoHexagon();           itfDraw = (IDraw)myHex;      // QI for IDraw.           itfDraw.Draw();           itfSE = (IShapeEdit)myHex;   // QI for IShapeEdit.           itfSE.Invert();      } }

The MS Java GC (garbage collector) automatically calls Release() on all interface references when necessary. Therefore, Java clients never see Release() calls at the Java source code level.

So then, at this point you can begin to use raw C++ COM objects from within the Visual Basic and Java languages, given the virtues of IDL. Not too bad! The last stop before a set of labs to try this all out for yourself is to see how type information can also be used to ease the burden of raw C++ client-side COM programming.

---