Adobe ColdFusion 8

Accessing Complex COM Objects using Java proxies

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

  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: Adobe 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.

    1. 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.
    2. 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 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 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:\CFusion\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 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.

Using the Application Scope to improve COM performance

The Java call to create a new COM object instance can take substantial time. As a result, creating COM objects in ColdFusion can be substantially slower than in ColdFusion 5. For example, on some systems, creating a Microsoft Word application object could take over one second using ColdFusion, while on the same system, the overhead of creating the Word object might be about 200 milliseconds.

Therefore, in ColdFusion, you can improve COM performance substantially if you can share a single COM object in the Application scope among all pages.

Use this technique only if the following are true:

  • The COM object does not need to be created for every request or session. (For session-specific objects, consider using the technique described in this section with the Session scope in place of the Application scope.)
  • The COM object is designed for sharing.

Because the object can be accessed from multiple pages and sessions simultaneously, you must also consider the following threading and locking issues:

  • For best performance, the object should be multithreaded. Otherwise, only one request can access the object at a time.
  • Lock the code that accesses and modifies common data. In general, you do not have to lock code that modifies a shared object's data, including writable properties or file contents, if the data (as opposed to the object) is not shared by multiple requests. However, specific locking needs depend on the COM object's semantics, interface, and implementation.
  • All cflock tags in the application that use an Application scope lock share one lock. Therefore, code that accesses a frequently used COM object inside an Application scope lock can become a bottleneck and reduce throughput if many users request pages that use the object. You might be able to avoid some contention by putting code that uses the COM object in named locks; you must put the code that creates the object in an Application scope lock.

Note: You can also improve the performance of some COM objects by creating Java stubs, as described in Accessing Complex COM Objects using Java proxies. Using a Java stub does not improve performance as much as sharing the COM object, but the technique works with all COM objects. Also, you must generate Java stubs to correctly access complex COM objects that do not properly make all their features available through the COM IDispatcher interface. Therefore, to get the greatest performance increase and prevent possible problems, use both techniques.