|
|
|
|
|
|
| | | |
The com2java Tool
WebLogic jCOM's com2java tool reads information from a type library, and generates Java files that can be used 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.
The following sections look at:
Using com2java
The com2java tool is in the bin subdirectory under the WebLogic jCOM installation directory. For example if you installed WebLogic jCOM in c:\bea\wlserver6.1\jcom, then you will find com2java in c:\bea\wlserver6.1\jcom\bin\com2java.exe.
As well as providing the GUI interface described below, a command line interface is provided via the com2javacmd tool. Type 'com2javacmd /?' for more information.
When you start com2java, this is the dialog that is displayed:
Selecting the type library
Click on 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 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.
Fill in the Java package text box with the name of the package to which you would like the generated files to belong.
The com2java tool will remember the last package name you specified for a particular type library.
Options
By clicking on the options button a dialog box with options for com2java appears. Note that these options are saved automatically between sessions of com2java. If you only require an option for one particular generation, then you must remember to reset the option after generating the proxies. The options are:
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 will prefix 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. If you would prefer the tool not to do so, 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 the above error. Selecting this option will ensure that the generated code retries each time this error code is received.
Generate Arrays as Objects
Parameters which 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 will assume 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 depreciated constructors
Generated proxies contain some constructors which are now depreciated. If you do not wish to generate these depreciated constructors at all 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, then selecting this option will cause the corresponding generated Java classes to not implement the additional interfaces. You can still access the interfaces using the getAsXXX method that is generated. See the generated comments.
Generate Java AWT classes
Generates .Java Classes as GUI classes. To be used for embedding ActiveX controls in Java Frames.
Generate the proxies
Click on the Generate Proxies ... button to select the directory in which the com2java tool should generate the Java files.
Once you select the directory, com2java will analyse the type library and output the corresponding files in the directory you specify. If the directory already contains Java source files, WebLogic jCOM will issue a warning and allow you to cancel the operation.
Files generated by com2java
The com2java tool processes three kinds of constructs in a type library:
You will need to refer to documentation associated with the COM objects that you are accessing in order 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:
Sometimes it is not easy to relate the generated files to the original API. If this is the case please do not hesitate to contact us. Ideally if you can give us a piece of code that works from another COM client (early-bound VB, VC++, etc.) then we will try to help you do the same from Java.
Enumerations
If a type library contains an enumeration, WebLogic jCOM will generate a Java interface containing constant definitions for each element in the enumeration.
COM Interfaces
There are two kinds of COM Interfaces that WebLogic jCOM handles. It handles Dispatch interfaces, whose methods can only be accessed using the COM IDispatch mechanism, and handes 'dual' interfaces, whose methods can also be invoked directly (vtbl access).
For each 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 will generate 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.
Although COM events work using Connection Points, and source interfaces, Java has a different event mechanism. The com2java tool totally 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 notices 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.
So for each event interface, WebLogic jCOM generates an adapter class.
Summary - Events
Please note that 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.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|