TechNote (Archived)

Accessing complex COM objects in ColdFusion MX using Java Stubs

Using pre-generated Java stubs for COM objects can improve COM performance in some cases. It can also enable access to some applications whose features are not easily available to Java environments through Microsoft Automation IDispatch interface.

ColdFusion MX supports Java proxies to access COM objects. If you do not create Java proxies in advance, ColdFusion must dynamically discover the COM interface. This technique can have two disadvantages:

Dynamic discovery takes time and can reduce server performance with frequently-used complex COM objects.
Dynamic discovery uses the IDispatcher interface to determine the COM object features, and might not handle some complex COM interfaces.

To overcome these problems, ColdFusion MX includes a utility, com2java.exe, that creates static Java stub proxy classes for COM objects. ColdFusion can use these Java stubs to access COM objects more efficiently than when it creates the proxies dynamically. Additionally, the com2java utility can create stubs for features that the dynamic proxy generator might miss.

ColdFusion MX ships with pre-generated stubs for the XP, 2000, and 97 editions of Microsoft Excel, Word, and Access. ColdFusion is configured to automatically use these stubs. If you create Java stub files for a COM object, you continue to use the cfobject tag with a type attribute value of COM or the CreateObject function with a first argument of COM, and you access the object properties and methods as you normally do for COM objects in ColdFusion.

Use the following steps to use the com2java.exe utility. This procedure uses Microsoft Outlook as an example:

To create Java stub files for COM objects

Configure your system as follows:
1. Ensure that a JDK (Java Development Kit) is correctly installed. including proper configuration of the CLASSPATH and the command prompt PATH variable.
2. Add cf_root\lib\jintegra.jar to your CLASSPATH.
Make a new directory for the Java stub files, for example:

mkdir C:\src\outlookXP

This directory can be temporary. You will add files from the directory to a ColdFusion JAR file.
Run the cf_root\Jintegra\bin\com2java.exe program from a command line or the Windows Start Menu Run dialog. A window appears.
1. If a COM class implements multiple interfaces which define methods with the same names, click the Options button and clear the Implement interfaces that may conflict option. The generated Java stub classes do not implement the additional, conflicting, interfaces. You can still access the interfaces using the getAsXXX method that is generated. See the generated comments in the Java files.
2. Click on the Select button.
3. Select your COM objectžs Type Library or dll. For OutlookXP, it is normally Program Files\Microsoft Office\Office10\MSOUTL.OLB.
4. Enter a package name in the Java package field of in the com2java dialog box; for example, outlookXP. This Java package will contain all the classes for the Java stubs for the COM object.
  
  Note: Macromedia uses a package name that starts with coldfusion.runtime.com.com2java for the packages that contain the preinstalled Java stubs for Excel, Word, and Access. For example, the name for the package containing the Microsoft Word XP Java stub classes iscoldfusion.runtime.com.com2java.wordXP. This package name hierarchy results in the wordXP classes having a path inside the msapps.jar file ofcoldfusion\runtime\com\com2java\wordXP\className.class. While this naming convention is not necessary, you should consider using a similar package naming convention for clarity, if you use many COM objects.
5. Click the Generate Proxies button to display the File browser. Select the directory you created in step 2, and click the file browser dialog OK button to generate the stub files.
6. Click Close to close the com2java tool.
The files generated in your directory include:
- A Java interface and proxy class for each COM interface
- A Java class for each COM class
- A Java interface for each ENUM (a set of constant definitions)
Compile your Java code. In a command prompt, do as follows:
1. Make the directory that contains the Java stubs (in this example, C:\src\outlookXP) your working directory.
2. Type following line:
  
  javac -J-mx100m -J-ms100m *.java
  
  The compiler switches ensure that you have enough memory to compile all the necessary files.
  
  Note: If you did not put jintegra.jar on your CLASSPATH in step 1b, add the switch -classpath:/cf_root/lib/jintegra.jar, wherecf_root is the directory where ColdFusion is installed, to the command.
Ensure that ColdFusion Server is not running. To stop the ColdFusion Server, open the Services control panel, select ColdFusion MX Application Server, and click Stop. (On Windows 98 or Me, select Stop ColdFusion MX from the ColdFusion MX Programs item on the Start menu.
Add your .class files to the ColdFusion Microsoft application Java stubs file by doing following:
1. In the Windows Command prompt, make the parent directory of the directory that contains your class files your working directory. In this example, make c:\src your working director by typing cd .. in the Command prompt from step 4.
2. Type the following command:
  
  jar -uvf cf_root\lib\msapps.jardirectoryName\*.class
  
  Where cf_root is the directory where ColdFusion MX is installed and directoryName is the name of the directory that contains the class files. For the OutlookXP example, type the following line: jar -uvf C:\CFusionMX\lib\msapps.jar outlookXP\*.class
Update the cf_root/lib/neo-comobjmap.xml file by appending your object definition to the list. The object definition consists of the following lines:
```
 <var name="progID"><string>PackageName.mainClass</string></var> 
```
Use the following values in these lines:
ProgID: the COM objectžs ProgID, as displayed in the OLE/COM object viewer.
PackageName: the package name you specified in step 3c.
mainClass: the main class of the COM object. The main class contains the methods you invoke. For many Microsoft applications, this class is Application. In general, the largest class file created in step 4 is the main class.

For example, to add Outlook XP to neo-comobjmap.xml, add the lines in bold text above the </struct> end tag:
```
 <var name="access.application.9"><string>coldfusion.runtime.com.com2java.access2k.Application</string></var><var name="outlook.application.10"><string>outlookXP.Application</string></var></struct> 
```
In this example, outlook.application.10 is the progID of the Outlook COM object, outlookXP is the package name you specified in step 3c, and Application is the COM objectžs main class.
Restart ColdFusion Server: Open the Services control panel, select ColdFusion MX Application Server, and click the Start button.
After you have installed the stubs, you can delete the directory you created in step 2, including all its contents.