Accessing .NET assemblies

ColdFusion provides two methods for accessing .NET assemblies:

• A local access method for .NET objects that are installed on the ColdFusion system
• A remote access method for .NET objects located on other systems.
  For both methods, install the ColdFusion .NET extension and run the ColdFusion .NET service on the system that hosts the assemblies. You need not install the extension or run the service on a ColdFusion system that accesses only remote assemblies. For information on installing the ColdFusion .NET extension, see Installing ColdFusion guide.

Accessing local assemblies

For local access, ColdFusion automatically generates and uses proxies for the required .NET assemblies when you first use the cfobject tag or CreateObject function. ColdFusion caches the proxies for future use, so it does not generate assembly proxies each time.
Usually when you are accessing local .NET assemblies, you do not have to override the default communication configuration settings. Sometimes you could have to specify these settings, however. If other software on your system uses the default 6086 port, for example, change the port number specification in the jnbridge\DotNetSide.exe.config file, and specify the changed port number in your cfobject tag or CreateObject tag. For information on changing the port number specification, see Configuring the .NET-side system below,
To use the local access method, use the cfobject tag or CreateObject function to create and access the proxy. You can use the resulting ColdFusion object to construct the .NET object, call the .NET object's methods, and access its fields. For detailed information on using .NET classes, see Using .NET classes.

Accessing remote assemblies

The remote access technique accesses .NET assemblies by using TCP or HTTP to communicate with a .NET-side agent on a remote system. You create proxy instances and call assembly methods as you do in the Local access method, but first configure the remote .NET-side agent and, in most cases, the proxy classes that represent the remote .NET classes.

Configure remote .NET access

1. On the remote system, install the ColdFusion .NET integration software and run the .NET-side agent (see Installing ColdFusion guide).
2. If the .NET assemblies reside only on the remote system, generate proxy JAR files on that system that represent the assemblies (see Generating the Java proxy classes below). Then copy or move the proxy files to the local system. If identical .NET assemblies also reside on the local system, you can skip this step.
3. Configure the .NET-side system for remote access (see Configuring the .NET-side system below).

Generating the Java proxy classes

The Java proxy generation code requires direct access to the .NET assemblies to generate the proxy classes. Therefore, if the system that runs your ColdFusion application does not have the assemblies installed, run a tool on the .NET-side system to create the Java proxies. ColdFusion installs two proxy generation programs, jnbproxyGui.exe and jnbproxy.exe in the jnbridge directory when you install the .NET services. The jnbproxyGui.exe program is a Windows user interface application, and the jnbproxy.exe program is a command line application. Both programs have identical capabilities.

On a ColdFusion system, the jnbproxyGui and jnbproxy programs are located in the cfroot\jnbridge directory. When you use the stand-alone installer, the programs are located in the installDir\jnbridge directory.
This document provides the basic information necessary to generate a proxy JAR file using the jnbproxyGui tool. Additional information is available in the following locations:

• The jnbridge directory includes a jnbproxy.chm Windows Help file with more complete documentation on the JNBridge technology that powers the ColdFusion .NET feature, including detailed information on both the jnbproxyGui and jnbproxy programs.
• The jnbridge\docs subdirectory includes additional documentation, including users guide.pdf, a PDF version of the information in the Help file.

Using the jnbproxyGui tool

You use the jnbproxyGui program to generate a proxy JAR file.

Generate and install a proxy JAR

1. Start JNBProxyGui.exe.
2. The first time you run the program, it displays the Enter Java Options dialog box. Configure the options, and click OK. You can change the configuration settings at a later time by selecting Project > Java Options.

On a system with ColdFusion: If ColdFusion is currently running on this system, ensure that the Start Java Automatically option, located on the right side of the JNBProxy Enter Java Options (Project > Java Options) dialog box is cleared. Leave the default values for the other settings.When you open an existing project, you could get a Restart Java Side pop-up window with the message "You must stop and restart the Java side before these changes to the classpath can take effect." You can ignore this message and click OK to proceed. When you start the program, the Java Options dialog box could appear. You do not have to change anything; click OK or Cancel to open the Launch JNBProxy dialog box.In some cases, JNBProxyGui could behave as follows when the Start Java Automatically option is not selected.

On a system without ColdFusion: If ColdFusion is not currently running on the system, ensure that the following options, which are located on the right side of the interface, are set. Leave the default values for the other settings.

1. • Ensure that the Start Java Automatically option is selected.
   • Specify the java.exe file to use to compile the JAR file. You can use a Java 1.4 or 1.5 (J2SE 5.0) version of this file.
   • Specify the jnbcore.jar file. The ColdFusion server installer places this file in the cfroot\lib directory. The J2EE installer places the file in the _cf_webapp_root_WEB-INF\cfusion\lib directory.
   • Specify the bcel.jar file. The ColdFusion server installer places this file in the cfroot\lib directory. The J2EE installer places the file in the _cf_webapp_root_WEB-INF\cfusion\lib directory.
2. In the Launch JNBProxy dialog box, select Create New Java > .NET Project, and click OK.
3. In the main Java proxy generation interface, set up and build a project:
   1. If you have not already done so, add the directory that contains your assembly files to the JNBProxy your project. Select Project >Edit Assembly List. In the Assembly List dialog box, click the Add button. In the New Assembly List Element dialog box, navigate to the directory that contains your assemblies. Select the directory (or directories) in the tree, and click OK. Then click OK in the Edit Assembly List dialog box.
   2. Open the Locate Assembly File dialog box (Project > Add Classes From Assembly File) and navigate to the directory that you added to the assembly list in step a. Select the assembly file or files that contain classes that require proxies and click OK.
   3. The classes in the selected file, and other .NET core classes on which they depend, appear in the Environment pane. Select all classes for which you want proxies in your JAR file, and click the Add+ button to add the selected classes and all supporting classes.
   4. In the Exposed Proxies list, select the classes to include in the JAR file. Normally, select all the listed classes, which ensures that all required classes are included.
   5. Select Project > Build from the main menu. In the Save Generated Proxies dialog box, specify the location and JAR file in which to save the generated proxies, and click Save.
   6. After the project is built, select File > Save Project and specify the file in which to save your project. The next time you run the jnbproxyGui program, you can select your project and reuse your previous settings, including the Assembly List.
4. Copy the JAR file to a directory on your ColdFusion system. You specify this path in the cfobject tag assembly attribute.

Supporting classes

JNBProxy can generate proxies not only for the .NET classes that are explicitly listed, but also for_ supporting classes_. A supporting class for a given .NET class is any class that could be needed as a direct or indirect result of using that .NET class. For a given .NET class, supporting classes include all of the following:

• The class.
• The class's superclass or superinterface (if it exists) and all of its supporting classes.
• The class's implemented interfaces (if any) and all of their supporting classes.
• For each field in the class:
  
  • The field's class and all of its supporting classes.
  • For each of the field's index parameters, the parameter's class and all of its supporting classes.
• For each method in the class:
  
  • The method's return value's class (if any) and all of its supporting classes.
  • For each of the method's parameters, the parameter's class and all of its supporting classes.
• For each constructor in the class, for each of the constructor's parameters, the parameter's class and all of its supporting classes.
  Unlike Java, where supporting classes include exceptions that methods throw, .NET supporting classes don't include thrown exceptions, because they are not declared in advance. 
  The number of supporting classes depends on the classes explicitly listed, but it often can be 200-250 classes. Usually you generate all supporting classes. However, to save time or space, you can generate only those classes explicitly specified, without supporting classes. 
  If a proxy for a supporting class has not been generated, and a proxy for such a class is later needed when the proxies are used, the proxy for the nearest superclass to the required class is used instead. If that proxy hasn't been generated, the proxy for the superclass of that superclass is used if it has been generated, and so forth, until the proxy for System.Object (which is always generated) is encountered. Thus, even with an incomplete set of proxies, code executes, although functionality and other information could be lost. 
  In the jnbproxyGui tool, when you click the Add button, the list includes only the explicitly listed classes. When you click the Add+ button, the list also includes the supporting classes. In the jnbproxy command line program, the default command generates proxies for the supporting classes; use the /ns option to override this default.

Configuring the .NET-side system

To configure the .NET-side system, you edit the jnbridge\JNBDotNetSide.exe.config configuration file in the following ways:

• For local assemblies, edit this file only if you do not use the default port, or if you use SSL security.
• For a .NET assembly on a remote machine, register the assemblies in this file to make it accessible to ColdFusion.

Edit the configuration file

1. Ensure that the following lines are in the <configSections> subsection of the <configuration> section:

   <javaToDotNetConfig scheme="Protocol" port="local port number" useSSL="true|false" certificateLocation="server certificate path"/> </jnbridge>

   • The scheme attribute specifies the communications protocol, and must be jtcp or http.
   • The port number is the port of the .NET-side agent, normally 6086.
   • The useSSL attribute specifies whether to use SSL for secure communications. The attribute is optional; the default is to not use SSL.
   • The certificateLocation attribute specifies the location of the server SSL certificate. It is required only if the useSSL attribute is true.
     These settings must be the same as the corresponding attributes in your cfobject tag.

2. If the .NET assemblies are on a remote system, specify the assemblies that ColdFusion accesses by adding the following elements inside the <jnbridge> section.

   <assembly file="path to assembly or fully qualified name"/> ... </assemblyList>

    

3. Stop and restart the .NET-side agent, if it is running. For example, on a ColdFusion system, restart the ColdFusion .NET Service. Your ColdFusion application can now access the .NET classes that you configured.
   The following example is a bare-bones JNBDotNetSide.exe.config file that specifies a .NET-side TCP server configuration. The server communicates by using TCP binary mode and listens on port 6086. Java clients can access \\\\x