A Closer Look at the jCOM Tools

WebLogic jCOM's com2java tool reads information from a type library, and generates Java files that you use to access the COM classes and interfaces defined in that type library.

Type libraries contain information on COM classes, interfaces, and other constructs. They are typically generated by development tools such as Visual C++ and Visual BASIC.

Some type libraries are readily identifiable as such. Files that end with the extension olb or tlb are definitely type libraries. What can be a little confusing is that type libraries can also be stored inside other files, such as executables. Visual BASIC puts a type library in the executable that it generates.

Click the Select button to select the type library that the tool should process.

Remember that type libraries can sometimes be hidden inside executable files, such as the executable or dynamic link library (DLL) containing your COM component.

The com2java tool will remember a list of the last type libraries you successfully opened and generated proxies for.

The com2java tool generates a set of Java source files corresponding to the COM classes and interfaces in the type library. You will probably want to have the generated files in a specific package. For example you may want to put all the files for the Excel type library in a Java package called excel.

In the Java package text box, specify the name of the package to which the generated files to belong.

The com2java tool remembers the last package name you specified for a particular type library.

Click the Options button to display a dialog box with com2java options described below. Note that these options are saved automatically between sessions of com2java. If you only require an option for one particular generation of proxies, then reset the option after generating the proxies.

Option	Description
Clash Prefix	If methods in the COM interfaces defined in the type library clash with methods that are already used by Java (for example the getClass() method), com2java prefixes the generated method name with a string, which is zz_ by default.
Lower case method names	The convention for Java method names is that they start with a lower-case letter. By default the com2java tool enforces this convention, changing method names accordingly. To have com2java ignore the convention, uncheck the Lowercase method names checkbox in the Options dialog box.
Only generate IDispatch	WebLogic jCOM supports calling COM objects using IDispatch and vtable access. Selecting this option ensures that all calls are made using the IDispatch interface.
Generate retry code on '0x80010001 - Call was rejected by callee'	If a COM server is busy, you may receive an error code. Selecting this option ensures that the generated code retries each time this error code is received.
Generate Arrays as Objects	Parameters that are SAFEARRAYS have a corresponding Java parameter of type java.lang.Object generated. This is required if you are passing two dimensional arrays outside of Variants to/from COM objects from Java. This option doesn't change what is actually passed over the wire —it is still arrays—it is just that in the generated Java interface, rather than having the generated method prototype specify the type of the array, it specifies "Object". This is useful in situations where you want to pass a 2D array —in the COM IDL the number of dimensions is not specified for SAFEARRAYS, and if you don't check the "generate arrays as objects" option, WebLogic jCOM assumes you are passing a single element array and generate a corresponding prototype. By setting the option, and having com2java generate "Object" instead of "String[]", for example, you are free to actually pass a 2D string array.
Prompt for names for imported tlbs	Sometimes a type library will import another type library. If you are also generating proxies for imported type libraries, using this option will prompt you for the package name of the those proxies.
Don't generate dispinterfaces	Selecting this option disables the generation of proxies for interfaces defined as dispinterfaces.
Generate deprecated constructors	Generated proxies contain some constructors which are now deprecated. If you do wish to generate these deprecated constructors select this option.
Don't rename methods with same names	If a name conflict is detected in a COM class, com2java automatically renames one of the methods. Selecting this option overrides this automatic renaming.
Ignore conflicting interfaces	If a COM class implements multiple interfaces which define methods with the same names, selecting this option prevents the corresponding generated Java classes from implementing the additional interfaces. You can still access the interfaces using the getAsXXX method that is generated. See the generated comments.
Generate Java Abstract Window Toolkit (AWT) classes	Generates Java Classes as GUI classes. To be used for embedding ActiveX controls in Java Frames.

Option

Description

Clash Prefix

If methods in the COM interfaces defined in the type library clash with methods that are already used by Java (for example the getClass() method), com2java prefixes the generated method name with a string, which is zz_ by default.

Lower case method names

The convention for Java method names is that they start with a lower-case letter. By default the com2java tool enforces this convention, changing method names accordingly. To have com2java ignore the convention, uncheck the Lowercase method names checkbox in the Options dialog box.

Only generate IDispatch

WebLogic jCOM supports calling COM objects using IDispatch and vtable access. Selecting this option ensures that all calls are made using the IDispatch interface.

Generate retry code on '0x80010001 - Call was rejected by callee'

If a COM server is busy, you may receive an error code. Selecting this option ensures that the generated code retries each time this error code is received.

Generate Arrays as Objects

Parameters that are SAFEARRAYS have a corresponding Java parameter of type java.lang.Object generated. This is required if you are passing two dimensional arrays outside of Variants to/from COM objects from Java.

This option doesn't change what is actually passed over the wire —it is still arrays—it is just that in the generated Java interface, rather than having the generated method prototype specify the type of the array, it specifies "Object". This is useful in situations where you want to pass a 2D array —in the COM IDL the number of dimensions is not specified for SAFEARRAYS, and if you don't check the "generate arrays as objects" option, WebLogic jCOM assumes you are passing a single element array and generate a corresponding prototype.

By setting the option, and having com2java generate "Object" instead of "String[]", for example, you are free to actually pass a 2D string array.

Prompt for names for imported tlbs

Sometimes a type library will import another type library. If you are also generating proxies for imported type libraries, using this option will prompt you for the package name of the those proxies.

Don't generate dispinterfaces

Selecting this option disables the generation of proxies for interfaces defined as dispinterfaces.

Generate deprecated constructors

Generated proxies contain some constructors which are now deprecated. If you do wish to generate these deprecated constructors select this option.

Don't rename methods with same names

If a name conflict is detected in a COM class, com2java automatically renames one of the methods. Selecting this option overrides this automatic renaming.

Ignore conflicting interfaces

If a COM class implements multiple interfaces which define methods with the same names, selecting this option prevents the corresponding generated Java classes from implementing the additional interfaces. You can still access the interfaces using the getAsXXX method that is generated. See the generated comments.

Generate Java Abstract Window Toolkit (AWT) classes

Generates Java Classes as GUI classes. To be used for embedding ActiveX controls in Java Frames.

Click the Generate Proxies button to select the directory in which the com2java tool should generate the Java files.

Once you select the directory, com2java analyzes.the type library and output the corresponding files in the directory you specify. If the directory already contains Java source files, WebLogic jCOM issues a warning and allows you to cancel the operation.

Refer to documentation about the COM objects that you are accessing to understand how to use generated Java files to manipulate the COM objects.

For example when you run com2java on the Excel type library the generated Java files you are seeing correspond to the Microsoft Excel COM API, and you should refer to the Microsoft Excel programming documentation for more information, such as the Excel 2000 COM API:

An enumeration is a list; in Java it is represented by java.util.Enumeration. If a type library contains an enumeration, WebLogic jCOM generates a Java interface containing constant definitions for each element in the enumeration.

WebLogic jCOM handles two types of interfaces. It handles Dispatch interfaces, whose methods can only be accessed using the COM IDispatch mechanism, and dual interfaces, whose methods can be invoked directly (vtbl access).

For each COM interface defined in a type library, the com2java tool generates two Java files: a Java interface, and a Java class.

The name of the generated Java interface is the same as the name of the COM interface. For example if the COM interface is called IMyInterface, the com2java tool generates a Java interface called IMyInterface in the file IMyInterface.java.

The second file that com2java generates is a Java class, which contains code used to access COM objects that implement the interface, and also code to allow COM objects to invoke methods in Java classes that implement the interface. The name of the generated Java class is the name of the interface with 'Proxy' appended to it. Using the example from the previous paragraph, WebLogic jCOM would generate a Java class called IMyInterfaceProxy in the file IMyInterfaceProxy.java.

For each method in the COM interface, WebLogic jCOM generates a corresponding method in the Java interface. In addition it generates some constants in the interface which, as the generated comments indicate, you can safely ignore—you will never need to know anything about them, or use them.

Once again, WebLogic jCOM picks up comments from the type library describing the interface and its methods, and uses them in the generated javadoc comments.

A COM class implements one or more COM interfaces, in the same way that a Java class can implement one or more Java interfaces.

For each COM class in a type library, the com2java tool generates a corresponding Java class, with the same name as the COM class. WebLogic jCOM also supports a class implementing multiple interfaces.

The Java class which WebLogic jCOM generates can be used to access the corresponding COM class.

A COM class can specify that an interface is a source interface. This means that it allows instances of COM classes that implement the interface to subscribe to the events defined in the interface. It invokes the methods defined in the interface on the objects that have subscribed.

Note: In order for the com2java tool to treat an interface in a type library as an Event interface, there must be at least one COM class in the type library that uses the interface as a source interface.

Although COM events work using connection points, and source interfaces, Java has a different event mechanism. The com2java tool hides the COM mechanism from the Java programmer, and presents the events using the standard Java techniques.

What this means in real terms is that com2java adds two methods to the Java class that it generates for accessing the COM Class.

When the com2java tool detects that a class uses an interface as a source interface, it generates special code for that interface. It derives the interface from the java.util.EventListener Java interface, as is the convention for Java events.

Another Java event convention is that each of the methods in the interface should have a single parameter, which is an instance of a class derived from java.util.EventObject Java class.

One final Java event related convention is the use of an Adapter class, which implements the event interface, and provides empty default implementations for the methods in the interface. That way, developers that wish to create a class which will be subscribed to the event need not implement all of the methods in the interface, which can be especially painful with large interfaces.

You can run java2com on any platform. Make sure that the WebLogic jCOM runtime weblogic.jar is in your CLASSPATH environment variable.

The java2com tool analyzes Java classes (using the Java reflection mechanism), and outputs:

After you generate these files, you will compile the IDL file using Microsoft's MIDL tool.

To generate the IDL file and the wrappers, first start the java2com tool using the command:

The dialog box has the following fields (any changes to the configuration are automatically saved when you exit the dialog box).

Field	Description
Java Classes and Interfaces	These are the 'root' Java classes and interfaces that you want java2com to analyze. They must be accessible in your CLASSPATH. WebLogic jCOM analyzes these classes, and generates COM IDL definitions and Java DCOM marshalling code which can be used to access the Java class from COM. It then performs the same analysis on any classes or interfaces used in parameters or fields in that class, recursively, until all Java classes and interfaces accessible in this manner have been analyzed. Separate the names with spaces. Click on the ... button to display a dialog that lists the classes and lets you add/remove from the list.
Name of Generated IDL File	This is the name of the COM Interface Definition Language (IDL) file which will be generated. If you specify myjvm, then myjvm.idl will be generated. This name is also used for the name of the type library generated when you compile myjvm.idl using Microsoft's MIDL compiler.
Output Directory	The directory to which java2com should output the files it generates. The default is the current directory (".").
Dump Analysis	Displays the classes that the java2com discovers, as it discovers them.
Save Settings/Load Settings	Click on the Save Settings button to save the current java2com settings. Do this before you click Generate. When java2com starts, it checks to see if there is a java2com.ser setting file in the current directory. If present, it loads the settings from that file automatically.
Names	Clicking the Names button displays the following dialog box: When '*' is selected from the class/interfaces names drop-down list, a text box is displayed into which you can type the name of a member (field or class) name. You may specify a corresponding COM name to be used whenever that member name is encountered in any class or interface being generated. If you leave the name blank then that Java member will not have a corresponding member generated in any COM interface. When a specific COM class name or interface is selected from the class/interfaces names drop-down list, the set of members in that class or interface is listed below it. You may specify a COM name to be used, and by clicking on Add this Class Name map you map the selected class/interface to the specified COM name. By clicking on Add this Member Name map you may map the selected member to the specified COM name.
Generate button	Click this button to generate the wrappers and IDL file. For each public Java interface that java2com discovers, it creates a corresponding COM interface definition. If the Java interface name were: com.bea.finance.Bankable, then the generated COM interface would be named ComBeaFinanceBankable, unless you specify a different name using the "Names" dialog. For each public Java class that java2com discovers, it creates a corresponding COM interface definition. If the Java class name were: com.bea.finance.Account, then the generated COM interface would be named IComBeaFinanceAccount, unless you specify a different name using the "Names" dialog. In addition if the Java class has a public default constructor, then java2com generates a COM class ComBeaFinanceAccount, unless you specify a different name using the "Names" dialog. If a Java class can generate Java events, then the generated COM class will have source interfaces (COM events) corresponding to the events supported by the Java class. Compile the generated IDL file using Microsoft's MIDL tool. This ships with Visual C++, and can be downloaded from the Microsoft web site. The command midl procdServ.idl produces a type library called prodServ.tlb, which you must register, as described in regtlb.

Field

Description

Java Classes and Interfaces

These are the 'root' Java classes and interfaces that you want java2com to analyze. They must be accessible in your CLASSPATH. WebLogic jCOM analyzes these classes, and generates COM IDL definitions and Java DCOM marshalling code which can be used to access the Java class from COM. It then performs the same analysis on any classes or interfaces used in parameters or fields in that class, recursively, until all Java classes and interfaces accessible in this manner have been analyzed.

Separate the names with spaces. Click on the ... button to display a dialog that lists the classes and lets you add/remove from the list.

Name of Generated IDL File

This is the name of the COM Interface Definition Language (IDL) file which will be generated. If you specify myjvm, then myjvm.idl will be generated. This name is also used for the name of the type library generated when you compile myjvm.idl using Microsoft's MIDL compiler.

Output Directory

The directory to which java2com should output the files it generates. The default is the current directory (".").

Dump Analysis

Displays the classes that the java2com discovers, as it discovers them.

Save Settings/Load Settings

Click on the Save Settings button to save the current java2com settings. Do this before you click Generate.

When java2com starts, it checks to see if there is a java2com.ser setting file in the current directory. If present, it loads the settings from that file automatically.

Names

Clicking the Names button displays the following dialog box:

When '*' is selected from the class/interfaces names drop-down list, a text box is displayed into which you can type the name of a member (field or class) name. You may specify a corresponding COM name to be used whenever that member name is encountered in any class or interface being generated. If you leave the name blank then that Java member will not have a corresponding member generated in any COM interface.

When a specific COM class name or interface is selected from the class/interfaces names drop-down list, the set of members in that class or interface is listed below it. You may specify a COM name to be used, and by clicking on Add this Class Name map you map the selected class/interface to the specified COM name. By clicking on Add this Member Name map you may map the selected member to the specified COM name.

Generate button

Click this button to generate the wrappers and IDL file.

For each public Java interface that java2com discovers, it creates a corresponding COM interface definition. If the Java interface name were: com.bea.finance.Bankable, then the generated COM interface would be named ComBeaFinanceBankable, unless you specify a different name using the "Names" dialog.

For each public Java class that java2com discovers, it creates a corresponding COM interface definition. If the Java class name were: com.bea.finance.Account, then the generated COM interface would be named IComBeaFinanceAccount, unless you specify a different name using the "Names" dialog. In addition if the Java class has a public default constructor, then java2com generates a COM class ComBeaFinanceAccount, unless you specify a different name using the "Names" dialog.

If a Java class can generate Java events, then the generated COM class will have source interfaces (COM events) corresponding to the events supported by the Java class.

Compile the generated IDL file using Microsoft's MIDL tool. This ships with Visual C++, and can be downloaded from the Microsoft web site. The command

midl procdServ.idl

produces a type library called prodServ.tlb, which you must register, as described in regtlb.

In order for WebLogic jCOM to allow languages supporting COM to access Java objects as though they were COM objects, you must register (on the COM client machine) a reference to the JVM in which the Java objects run. The regjvm tool enables you to create and manage all the JVM references on a machine.

Note: The regjvm tool does not overwrite old entries when new entries with identical names are entered. This means that if you ever need to change the hostname or port of the machine with which you wish to communicate, you have to unregister the old entry and then reregister the entry. You can do this using the command line tool regjvmcmd.exe, or by using the GUI tool regjvm.exe (both can be found in the WL_HOME\server\bin directory).

DCOM mode does not require any native code on the Java server side, which means your Java code may be located on a Unix machine or any machine with a Java Virtual Machine installed. When you register the JVM on the Windows client machine you define the name of the server host machine (it may be localhost for local components) and a port number.

The Java code in the JVM must call com.bea.jcom.Jvm.register(<jvm id>), where <jvm id> is the id of the JVM as defined in regjvm.

Native mode currently only works on the local machine. Other than the JVM name no additional parameters are necessary.

The JVM must call com.bea.jcom.Jvm.register(<jvm id>), where <jvm id> is the id of the JVM as defined in regjvm.

Using native mode in process allows the user to actually load the Java object into the same process as the COM client. Both objects must of course be located on the same machine.

The JVM need not call com.bea.jcom.Jvm.register() or be started as an extra process to the client.

regjvmcmd is the command line version of the GUI tool, regjvm, discussed in regjvm. To get a summary of its parameters, run it without parameters:

If you no longer need to have the JVM registered, or if you wish to change its registration, you must first un-register it with this command:

WebLogic jCOM's regtlb tool registers a type library on a COM Windows client that needs to access Java objects using COM's early binding mechanism. regtlb takes two parameters. The first is the name of the type library file to be registered. The second is the ID of the JVM in which the COM classes described in the type library are to be found.

If the type library was generated from an IDL file that was in turn generated by the WebLogic jCOM java2com tool, then the regtlb command can automatically determine the Java class name corresponding to each COM class in the type library (the COM class descriptions in the type library are of the form:

If the type library was not generated from a java2com generated IDL file, you will be prompted to give the name of the Java class which is to be instantiated for each COM class:

This means that when someone attempts to create an instance of Atldll.Apple, WebLogic jCOM will instantiate com.bea.MyAppleClass in the JVM MyJvm. The MyAppleClass class should implement the Java interfaces generated by WebLogic jCOM's java2com tool from atldll.tlb that are implemented by the COM class Atldll.Apple.