A Closer Look at the jCOM Tools

A Closer Look at the jCOM Tools

The following sections examines in detail the tools used by jCOM applications:
com2java
java2com
regjvm
regjvmcmd
regtlb

com2java

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.

Using com2java

Start com2java by typing it in a command shell or double clicking its icon.
When you start com2java, this is the dialog that is displayed:

Selecting the Type Library

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.

Specifying the Java Package Name

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.

Options

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.

Generate the Proxies

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.

Files Generated by com2java

The com2java tool processes three kinds of constructs in a type library:
Enumerations
COM Interfaces
COM Classes

These are explored in this section.
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:
http://msdn.microsoft.com/library/default.asp?URL=/library/officedev/off2000/xltocobjectmodelapplication.htm

Enumerations

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.

COM Interfaces

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.

COM Classes

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.

Special Case - Source Interfaces (Events)

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.
For each event interface, WebLogic jCOM generates an adapter class.

java2com

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:
A COM Interface Definition Language (IDL) file
Pure Java DCOM marshalling code (wrappers) used by the WebLogic jCOM runtime to facilitate access to the Java objects from COM using vtable (late binding) access.

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:
java com.bea.java2com.Main
The java2com tool displays the following dialog box:

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 commandmidl procdServ.idl produces a type library called prodServ.tlb, which register, as described in regtlb.

regjvm

In order for WebLogic jCOM to allow languages supporting COM to access Java objects as though they were COM objects, 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 that 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).

JVM Modes

You can access a JVM from COM clients in one of three different modes:
DCOM mode
Native mode (out of process)
Native mode in process

DCOM mode

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 Out of Process

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.

Native Mode in Process

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.

The User Interface of the regjvm GUI Tool

Run the regjvm tool to display the following dialog box.

The top part is for selection and management of all JVMs on the current machine. You can change, add or delete JVMs. Before switching to a different JVM, save changes made to the currently selected JVM. The JVM mode you select dictates the information required in the lower half of the screen.
The lower half of the windows contains the details required for each JVM, according to the mode of the JVM. In addition to the JVM details there is an advanced checkbox which when selected displays advanced options for each JVM mode.
These options are discussed in the following sections.

DCOM Mode Options for the regjvm GUI Tool

Standard Options
JVM id (required) - The JVM must be specified. Clicking the browse button allows you to select your own JVM, clicking the Scan button scans your local machine for JVMs (this may take a few minutes) and inserts them in the listbox for your selection.
Hostname - The hostname or IP address where the JVM is located.
Port - The port number used to initiate contact with the JVM.

Advanced Options
Launch command (required) - The command to be used if the JVM is to be automatically launched. Typically this would be something like:
c:\bea\jdk131\bin\java -classpath c:\bea\weblogic700\server\lib\weblogic.jar;c:\pure MyMainClass
The important thing is that weblogic.jar and the appropriate jdk files be in your CLASSPATH.
Generate Script (optional) - Allows the user to generate a registry script selecting the settings of the JVM.

Native Mode Options for the regjvm GUI Tool

Standard Options
JVM id (required) - The JVM must be specified. Clicking the browse button allows you to select your own JVM, clicking the Scan button scans your local machine for JVMs (this may take a few minutes) and inserts them in the listbox for your selection.

Advanced Options
The advanced options are identical to those of DCOM mode. See DCOM Mode Options for the regjvm GUI Tool.

Native Mode in Process Options for the regjvm GUI Tool

Standard Options
JVM id (required) - The JVM must be specified. Clicking the browse button allows you to select your own JVM, clicking the Scan button scans your local machine for JVMs (this may take a few minutes) and inserts them in the listbox for your selection.

Advanced Options
Classpath (optional) - The CLASSPATH for the JVM. If this is left blank the CLASSPATH environment variable at runtime is used. Otherwise the contents are added to the CLASSPATH environment variable.
Main class (optional) - The name of the class containing a Main method which you wish to be called.
Properties (optional) - Any properties which you require to be set. Must have the following syntax: prop1=value1 prop2=value2...
Java 2 (optional) - When setting properties this must be set when using Java 2 (JDK 1.2.x, 1.3.x) and cleared when using 1.1.x.
Generate Script (optional) - Identical to that of DCOM mode. See DCOM Mode Options for the regjvm GUI Tool.

regjvmcmd

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:
regjvmcmd
In regjvmcmd's simplest form, you specify the following:
A jvm ID (corresponding to the name used in com.bea.jcom.Jvm.register("JvmId")),
The binding that can be used to access the JVM, in the form hostname[port], where hostname is the name of the machine running the JVM, and port is the TCP/IP port specified when starting WebLogic Server.

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

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:
Java class java.util.Observable (via jCOM))
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.

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.

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 commandmidl procdServ.idl produces a type library called prodServ.tlb, which register, as described in regtlb.