Accessing Complex COM Objects using Java proxies

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.exe utility can create stubs for features that the dynamic proxy generator might miss.

ColdFusion MX ships with pregenerated stubs for the Windows XP, Windows 2000, and Windows 97 editions of Microsoft Excel, Microsoft Word, and Microsoft Access. ColdFusion MX 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:

1. 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.
2. Make a new directory for the Java stub files; for example:

   mkdir C:\src\outlookXP
   

   This directory can be temporary. You add files from the directory to a ColdFusion JAR file.

3. Run the CF_root\Jintegra\bin\com2java.exe program from a command line or the Windows Start Menu. A window appears.
   1. If a COM class implements multiple interfaces that 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 Microsoft Outlook in Windows XP, it is normally Program Files\Microsoft Office\Office10\MSOUTL.OLB.
   4. Enter a package name (for example, outlookXP) in the Java package field in the com2java dialog box. This 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 Microsoft Excel, Microsoft Word, and Microsoft Access. For example, the name for the package containing the Microsoft Word XP Java stub classes is coldfusion.runtime.com.com2java.wordXP. This package name hierarchy results in the wordXP classes having a path inside the msapps.jar file of coldfusion\runtime\
   com\com2java\wordXP\className.class. Although this naming convention is not necessary, 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 OK button to generate the stub files.
   6. Click Close to close the com2java.exe utility.

   The files generated in your directory include the following:

   • 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)
4. Compile your Java code. In a command prompt, do the following:
   1. Make the directory that contains the Java stubs (in this example, C:\src\outlookXP) your working directory.
   2. Enter the 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, where cf_root is the directory where ColdFusion is installed, to the command.

5. Ensure that the ColdFusion server is not running. To stop the ColdFusion server, open the Services control panel, select ColdFusion MX application server, and click Stop.
6. Add your .class files to the ColdFusion Microsoft application Java stubs file by doing the 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 entering cd .. in the Command prompt from step 4.
   2. Enter the following command:

   	jar -uvf cf_root\lib\msapps.jar directoryName\*.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, enter the following line:
   	jar -uvf C:\CFusionMX7\lib\msapps.jar outlookXP\*.class
   

7. 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 outlookXP 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.

8. Restart the ColdFusion server: Open the Services control panel, select ColdFusion MX application server, and click the Start button.
9. After you have installed the stubs, you can delete the directory you created in step 2., including all its contents.

View comments in LiveDocs