Occasionally, the use of additional tools for generating proxies and running the .NET extension software can be helpful in some workflows.
Using the jnbproxy command
You can use the jnbproxy command-line tool as an alternative to the jnbproxyGui program, to generate Java proxies. For more information, see Generating the Java proxy classes in Accessing .NET assemblies.
For example, you can use this command in a batch file to generate multiple proxy JAR files in a single operation.
The jnbproxy command has the following format:
jnbproxy options... classes... |
For example:
jnbproxy /al C:\dotNet\netdll\PrimitiveTypes.dll /d C:\dotNet\MyJavajars |
Options
The following table lists the options that you can use. To create proxies on a system that is running ColdFusion, use the /nj option and do not specify the /bp, /java, or /jp options.
Option |
Req/Opt |
Default |
Description |
|---|---|---|---|
/al assemblylist |
Required |
|
Specifies a semicolon-separated series of file paths of .NET assemblies (DLL and EXE files) that contain the required .NET classes. |
/bp bcelpath |
Optional |
Use the CLASSPATH environment variable to locate the file. |
Specifies the path to the folder that contains the bcel.jar file. Ignored if you use the /nj option. |
/cf |
Required |
|
Use the ColdFusion software license. If you do not include this option, your proxies are limited to a 30-day trial period. |
/d directory |
Optional |
The current execution directory. |
Specifies the directory in which to write a JAR file with the generated proxies. |
/f classfile |
Optional |
|
Reads the classes from the specified text file, not the command line. For more information, see the JNBridge documentation. |
/h |
Optional |
|
Lists the options and usage information. Typing the command jnbproxy with no options or arguments results in the same information. |
/host hostname |
Required |
|
Specifies the host on which the .NET code is located. This option can be a host name or an IP address. Normally, you specify localhost. |
/java javapath |
Optional |
Use the first java.exe file found using the system PATH environment variable. |
Specifies the path of the directory that contains the java.exe program to use when automatically starting Java. Ignored if you use the /nj option. |
/jp jnbcorepath |
Optional |
Use, the CLASSPATH environment variable. |
Specifies the path of the folder containing the file jnbcore.jar. Ignored if you use the /nj option. |
/ls |
Optional |
Generate and list the proxies. |
Lists all classes that are generated in support of the specified classes (see Supporting classes in Accessing .NET assemblies), but don't generate the proxies. |
/n name |
Optional |
Create a file named jnbproxies.jar. |
Specifies the name of the JAR file in which to place the proxies. Do not specify the .jar extension; the tool automatically adds it. |
/nj |
Optional |
Start Java automatically. |
Does not start Java automatically. If you use this option, Java must be running, and the /bp, /java, /jp, and /wd options, if present, are ignored. |
/ns |
Optional |
Generate proxies for all supporting classes. |
Generates proxies for the classes specified on the command line (or class file) only, not for any supporting classes. |
/pd |
Required |
|
Specifies the direction in which the proxies operate. Must be j2n. |
/port portNum |
Required |
|
Specifies the port on which the .NET side listens when generating the proxies. Must be an integer. Normally this value is 6085. |
/pro protocol |
Required |
|
Specifies the communication mechanism between the .NET and Java sides. The valid values are:
|
/wd dir |
optional |
The system's default working directory. |
Specifies the working directory for the JVM.Ignored if the /nj option is present. |
Classes
A space-separated sequence of fully qualified .NET class names (for example, CSharpDatatypes.PrimitiveTypes) for which to generate proxies. The proxies for System.Object and System.Type are always generated, even if they are not listed in the class list.
Passing data by reference and value
The proxy generators let you specify whether to pass parameters and return values by reference or by value.
About passing by reference and value
When you pass data by reference, the information transferred between the Java Proxy and the .NET side is a logical pointer to the underlying .NET object, which continues to reside on the .NET side. When you pass data by value, the transferred information contains a copy of the contents of the .NET object, which could or continue to reside on the .NET side after a function call. Passing by reference and value have different advantages.When you pass data by reference, only changed values are passed between the Java proxy and the .NET object directly. All other information is passed as reference to its representation in the corresponding objects. Because the reference is typically much smaller than the actual object, passing by reference is typically fast. Also, because the reference points to a .NET object that continues to exist on the .NET side, if that .NET object is updated, the updates are immediately accessible to the proxy object on the Java side. The disadvantage of reference proxies is that any access to data in the underlying object (for example, field or method accesses) requires a round trip from the Java side to the .NET side (where the information resides) and back to the Java side.When you pass data by value, a copy of the data is passed between .NET and Java. Because the data object itself is typically bigger than a reference, passing an object by value takes longer than passing it by reference. Also, the value that is passed is a snapshot of the object taken at the time that it was passed. The passed object maintains no connection to the underlying .NET object, therefore, the passed value does not reflect any updates to the underlying .NET object that are made after the object is passed. The advantage of passing data by value proxies is that all data in the object is local to the Java side, and field accesses are fast, because they do not require a round trip to the .NET side and back to get the data.The choice of whether to use reference or value proxies depends on the desired semantics of the generated proxies, and on performance.
- In general, use reference proxies (the default), because they maintain the normal parameter-passing semantics of Java and C#.
- In general, use value proxies in any of the following cases:
- The class functions always must pass parameter values and return values back and forth.
- The class object contains little data.
- The object data changes frequently, and the object is either relatively small or the frequency of accesses to data outweighs the time taken to transfer the object.
Specifying the data passing method
When you use the JNBProxy.gui tool to generate proxies, you can designate the proxies that pass by reference and which proxies pass by value. The default proxy type is reference.To set the data passing method for a class, right-click on the class in the Exposed Proxies pane. Select the desired passing method from the list that appears. After you select the passing method, the color of the proxy class changes, to indicate its type: black for reference, or blue for value (public fields/properties style).
Set the passing method for multiple proxy classes simultaneously
- Select Project > Pass By Reference / Value from the menu bar.
- The Pass by Reference / Value dialog box lists all proxy classes in the Exposed Proxies pane. Select the classes whose passing value you want to set.
- Click the Reference or Value (Public fields/properties) button to associate the selected classes to the desired type.
- Repeat steps 2 and 3 to select multiple groups of classes and set their passing methods.
- Click OK.
Determining and changing the .NET version
If you get errors when using a .NET object in your application, you could have version issues. For example, many Microsoft system classes were added in .NET Version 2.0, including System.IO.DriveInfo and System.Net.NetworkInformation.Ping. For examples of these classes in applications, see Using .NET objects in Using .NET classes and Using a .NET class directly in Example applications, respectively.
Use the following function to get the current .NET version:
<cfset var seClass=""> |
If the function reports that the active version is not the one you require, install or reinstall the correct version of the .NET framework redistributable package on the system that runs ColdFusion. Then reinstall the ColdFusion .NET extension so that it uses the correct .NET version.
Running the .NET extension agent as an application
The ColdFusion .NET extension installer configures the .NET-side extension agent to run automatically as the ColdFusion .NET service. You can also run the .NET extension agent as an application.
Run the .NET extension agent as an application
- Ensure that you stopped the ColdFusion .NET service, if it was running.
- Open a command prompt window and navigate to the jnbridge directory. On a stand-alone ColdFusion server configuration, this directory is installDir\jnbridge. On a system with a stand-alone .NET extension installation, or a JEE configuration, it is in the .NETInstallDir\jnbridge directory, and the default installation directory is C:\ColdFusonDotNetExtension.
Enter the following command:
JNBDotNetSide