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

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.

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

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.

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

3. In the Launch JNBProxy dialog box, select Create New Java > .NET Project, and click OK.

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

5. Copy the JAR file to a directory on your ColdFusion system. You specify this path in the cfobject tag assembly attribute.

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.

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.

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

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

   <assemblyList>  
       <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

<?xml version="1.0" encoding="utf-8"?>  
<configuration>  
    <sectionGroup name="jnbridge">  
        <section name="dotNetToJavaConfig" 
                type="System.Configuration.SingleTagSectionHandler"/>  
        <section name="javaToDotNetConfig" 
                type="System.Configuration.SingleTagSectionHandler"/>  
        <section name="tcpNoDelay" 
                type="System.Configuration.SingleTagSectionHandler"/>  
        <section name="javaSideDeclarations" 
                type="System.Configuration.NameValueSectionHandler"/>  
        <section name="assemblyList" 
                type="com.jnbridge.jnbcore.AssemblyListHandler, JNBShare"/> 
    </sectionGroup>  
    <jnbridge>  
        <javaToDotNetConfig scheme="jtcp" port="6086"/>  
        <assemblyList>  
            \\x 
            <assembly file="System.Windows.Forms, Version=1.0.5000.0, 
                Culture=neutral, PublicKeyToken=b77a5c561934e089"/>  
        </assemblyList>  
    </jnbridge> 
</configuration>