Overview of Installation

JNBridgePro includes a comprehensive set of evaluation and installation guides. This includes a PDF readme file as well as documentation for installations of the following containers:

• JNBridgePro with Borland Enterprise Server 5.0

• JNBridgePro with JBoss - Tomcat

• JNBridgePro with JRun

• JNBridgePro with Oracle9iAS

• JNBridgePro with Sybase EAserver 4.x

• JNBridgePro with WebLogic 6.1

• JNBridgePro with WebLogic 7.0

• JNBridgePro with WebSphere 4.0

• JNBridgePro with WebSphere 5.0

A little later in the chapter, we will look at an example using WebSphere’s 5.0 server edition.

The general procedure for installing JNBridgePro is as follows:

1. Run the installer jnbSetup1_1ee.msi or jnbSetup1_1se.msi on the development machines where proxies are generated.

2. Configure the communications on the appropriate .NET and Java machine(s).

3. Copy the appropriate component and configuration files to the respective .NET-side and Java-side machines, and modify the configuration files as directed for runtime proxy-use deployment.

For an understanding of the specifics involved in installation, let’s review the related topics as they are presented in the JNBridge guide.

Architectural Elements

When JNBridgePro is used to interoperate .NET and Java code, the .NET code runs on a .NET Common Language Runtime (CLR) and Java code runs on a Java Virtual Machine (JVM). Every application using JNBridgePro consists of one or more instances of the CLR and one or more JVM instances.

Note

Here, the set of all .NET CLRs in an application are collectively referred to as the “.NET-side,” while the set of all instances of the JVM are referred to as the “Java-side.”

The .NET-side and the Java-side can run on the same machine or on different machines connected by a network. The .NET-side must reside on a Microsoft .NET supported machine; the Java-side can reside on any machine with a standards- compliant JVM.

Configuring the .NET-Side

A copy of the .NET Framework must reside on the .NET-side. In addition, the .NET classes using JNBridgePro require the .NET-side to have a copy of jnbshare.dll, as well as a copy of the DLL file containing the generated proxies. These two DLL files must reside in the same folder as the application using them.

The configuration file jnbproxy.config must reside in the same folder as jnbshare.dll. If HTTP/SOAP is used for communications between .NET and Java, jnbproxy.config must contain a copy of jnbproxy_http.config. Conversely, if the binary protocol is used, jnbproxy.config must contain a copy of jnbproxy_tcp.config supplied with the JNBridgePro software distribution. Additionally, the configuration file must be edited to indicate the name or IP address of the host on which the Java classes reside, as well as the port number on which the Java-side listens for messages. If both the .NET-side and the Java-side reside on the same machine, the host name “localhost” may be used.

Since the .NET Framework supports distributed computing, the .NET-side can reside on several different machines, where classes communicate with each other through .NET remoting. If this scenario exists, each .NET-side machine communicating with the Java-side must contain a local copy of the generated proxy DLL file, jnbshare.dll, and jnbproxy.config.

Configuring the Java-Side

A copy of the Java Runtime Environment (JRE) must reside on the Java-side. If the Java-side resides on more than one machine, each respective machine must contain a JRE copy. The Java-side must also include any Java classes being accessed and must therefore have a copy of jnbcore.jar on each machine where the Java-side resides. The locations of the Java classes and jnbcore.jar must be in either the CLASSPATH environment variable or must be supplied to the Java runtime when invoked. Moreover, the Java-side must contain a copy of jnbcore.properties. Depending on whether communication is via HTTP/SOAP or binary protocol, jnbcore.properties should have a copy of one of the prototype properties files, jnbcore_http.properties or jnbcore_tcp.properties. Edit the Ports field in the properties file to indicate the port on which the Java-side should listen to messages from the .NET-side.

The Java-side for an application can reside on more than one machine, with the restriction that .NET classes sitting on one machine may only communicate with the Java classes on a single machine.

About Communications Protocols

JNBridgePro supports communication between .NET and Java code using two communications protocols:

• Proprietary binary protocol

• HTTP/SOAP communications protocol

The binary protocol is fast and efficient but may not penetrate corporate firewalls; the HTTP/SOAP protocol is slower, but will pass through firewalls. JNBridgePro recommends using the faster proprietary binary protocol.

If communications between .NET and Java employ HTTP/SOAP, a copy of a JAXP-compliant XML package must reside on the Java-side. Any such package may be used; one such package is located on Sun’s JAXP site (http://java.sun.com/xml/jaxp/index.html ). Installation details vary for each package. Programmers should consult instructions included with the selected package. To use HTTP/SOAP communications, the locations of the files in the JAXP package must either appear in the CLASSPATH environment variable, or they must be supplied to the Java runtime when invoked.

Table 8-1 lists JNBridgePro components and related configuration files.

Table 8-1: JNBridgePro Development Components

Component	File Name	Description
JNBProxy GUI version	jnbproxygui.exe	Generates .NET proxies enabling .NET classes to communicate with Java classes.
JNBProxy command-line version	jnbproxy.exe	Represents the command-line version of the proxy generation tool.
JNPBCommon	jnbpcommon.dll	Contains functionality shared by the GUI and command-line versions of JNBProxy.
Generated proxies	*.dll	A .NET assembly contains the generated proxies built especially for the application.
JNBShare	jnbshare.dll	A .NET assembly contains core functionality used by generated .NET proxies.
JNBCore	jnbcore.jar	A Java JAR file that manages communications for both Java and .NET classes, as well as the object's life cycle—that is, creation, use, and object destruction of Java objects created by calls from .NET objects.
Registration tool	registrationTool.exe	Registers and licenses JNBShare on additional machines where the proxy generation tool has not been installed.
.NET-side proxy configuration file	jbnproxy.config	Specifies on the .NET-side, the protocol, host, and port used to communicate between .NET classes and Java classes.
Java-side configuration file	jnbcore.properties	Specifies on the Java side, the protocol and port number to communicate between the user's .NET classes and the Java classes.

Executing the Installer

To install the JNBridgePro development components for proxy generation, double-click on the installer file jnbSetup1_1ee.msi or jnbSetup1_1se.msi, and follow the instructions, selecting one of the following options:

• Development configuration (proxy generation tools, plus Java and .NET runtime components)

• Deployment configuration (Java and .NET runtime components only)

In either case, the installer installs the files jnbshare.dll, jnbcore.jar, and registrationTool.exe, as well as sample configuration files and additional documentation. If the programmer selects the development configuration, the files jnbproxy.exe, jnbproxygui.exe, and jnbpcommon.dll are installed as well.

Configuring the Communications Protocol

As you already know, JNBridgePro supports communications between .NET classes running in a CLR and Java classes running in a JVM. The CLR and the JVM can reside on the same machine or on different machines. The JNBProxy proxy generation tool is simply a .NET application communicating with Java classes like any other .NET application utilizing JNBridgePro. Therefore, JNBProxy also requires a CLR and a JVM, existing on either the same or different machines.

1. Navigate to the folder in which jnbproxy.exe and jnbproxygui.exe were installed (for example, C:\Program Files\JNBridge\JNBridgePro).

2. Generate a new configuration file, jnbproxy.config, specifying the protocol (HTTP/SOAP or binary) used to communicate between .NET and Java classes.

   • For HTTP/SOAP, copy jnbproxy_http.config to jnbproxy.config.

   • For binary protocol, copy jnbproxy_tcp.config to jnbproxy.config.

3. Modify the new jnbproxy.config file in order to reflect the proper host name and port number for the Java runtime component.

   • Open jnbproxy.config using a text editor and locate the URL, which will either be http://localhost:8085/JNBDispatcher, for HTTP/SOAP, or jtcp://localhost:8085/JNBDispatcher, for the binary protocol.

   • Edit the host name (currently “localhost”) and port number (currently “8085”) to indicate the host on which the Java classes and the JNBCore component will reside and the port on which JNBCore will be listening for messages. If JNBCore resides on the same machine as the .NET classes, leave the host as “localhost.”

4. The default JNBCore is residing on the same machine as the .NET classes; JNBCore listens on port 8085. If this is acceptable, do not change the configuration file. Save it, and close the text editor.

5. Copy the jnbcore directory into a location of choice on the machine where the Java environment resides. This directory contains the Java runtime component jnbcore.jar and two properties files, jnbcore_http.properties and jnbcore_tcp.properties. This directory must be on the same machine as the Java classes accessed from .NET code. Add the JAR’s full path to the CLASSPATH environment variable.

6. Generate a new properties file, jnbcore.properties, corresponding to the protocol used to communicate between .NET classes and Java classes.

   • For HTTP/SOAP, copy jnbcore_http.properties to jnbcore.properties.

   • For binary protocol, copy jnbcore_tcp.properties to jnbcore.properties.

7. On the Java machine, open jnbcore.properties using a text editor. Edit the value of the port to agree with the value chosen in jnbproxy.config. Save the file, and close the text editor. The resultant file should look like the following:

    serverType=tcp 
   workers=5
   timeout=10000
   port=8085

If using HTTP/SOAP for communications between the .NET classes and Java classes, and a JAXP-compliant XML package is not installed, install one. If using the binary protocol, skip this step.

Note

Any JAXP-compliant XML package can be installed. Follow the installation instructions for the selected package. Following installation, add the JAR file’s full path to the CLASSPATH environment variable.

Improving Network Performance

By default, JNBridgePro sends out network packets between the .NET and Java sides as soon as they are created. In most cases, this leads to improved performance. However, this behavior means that typical JNBridgePro-generated network packets are small, and in some cases this could lead to network congestion and degraded performance. If network performance degradation occurs, turn off the NoDelay option so packets are aggregated before they are sent out. This may improve network performance. Typically, if calls or returns contain a large amount of data, turning NoDelay off may improve performance. The NoDelay option can also be controlled independently in the .NET-to-Java and Java-to-.NET directions. To turn the NoDelay option off in the .NET-to-Java direction, add the following to the .NET application’s configuration file. For example, if the application is x.exe, create or open the file x.exe.config in the same folder as x.exe and add the following to the file:

<configuration>
<appSettings>
<add key="JNBridge_TCP_NoDelay" value="false"/>
</appSettings>
</configuration>

To turn the NoDelay option off in the Java-to-.NET direction, add the following line to the jnbcore.properties file: nodelay=false.

Starting Java for Proxy Generation

JNBProxy uses the Java reflection API to discover information about Java classes for which it is generating proxies. To do this, a JVM must be running that contains the JNBCore component and the Java classes for generating proxies.

JNBProxy users (both the GUI and command-line versions) may choose to have the Java-side started automatically or manually. If the Java-side resides on some other machine, JNBProxy will be unable to start; therefore, a manual start is required. To manually start the Java-side, issue the following command from the command-line:

java –cp classpath com.jnbridge.jnbcore.JNBMain /props propFilePath 

where classpath must include the following:

• The Java classes for which proxies are generated (and their supporting classes).

• jnbcore.jar.

• The JAR files for the XML package (if using HTTP/SOAP communication).

• The –cp classpath option can be omitted, in which case the required information must be present in the CLASSPATH environment variable: propFilePath is the full file path of the file jnbcore.properties.

The folder containing the java.exe executable must be in the system’s search path (typically described in the PATH environment variable). If not, specify the full path of java.exe on the command line.

When starting the Java-side manually, you will see the following output if using the binary protocol:

JNBCore v1.2
Copyright 2002, JNBridge
creating binary server

Or the following output will be seen if HTTP/SOAP is used:

JNBCore v1.2
Copyright 2002, JNBridge
creating http server

Configuring the System for Proxy Use

To deploy JNBridgePro runtime components for proxy use (that is, on machines other than ones containing the proxy generator), copy and run the installer on those machines, and select Deployment Configuration when requested by the installer. Also create versions of the configuration files jnbproxy.config and jnbcore.properties as described in the earlier section “Configuring the Communications Protocol.” JNBridgePro searches for the configuration file jnbproxy.config in the following folders:

• It looks first in the folder where jnbshare.dll is located.

• If not located there, it looks in the folder <System-drive>:\Inetpub\wwwroot, where <System-drive> is the drive on which the running system is installed (typically C, but not always). If the proxies are called from ASP.NET, place jnbproxy.config in this folder.

If jnbshare.dll is not found there, JNBridgePro looks in the folder <System-drive>:\ (the root folder of the drive on which the system is installed, typically C, but not always). Any user accessing proxies generated by JNBridgePro must specify Read and Write access to the folder <System-drive>:\Documents and Settings\AllUsers\ Application Data\Microsoft\Crypto\RSA\MachineKeys.

If the user does not have access to this folder, the proxies cannot be used. This is only an issue on systems running the NTFS file system. On systems running other file systems, users should automatically have this access.

Configuring Proxies for Use with ASP.NET

If the developer is calling the generated proxies from ASP.NET, place the configuration file jnbproxy.config in the folder <System-drive>:\Inetpub\wwwroot, where <Systemdrive> is the drive on which the running system is installed (typically C). If the ASP.NET machine is running on an NTFS file system, make sure the user account has Read and Write access to the folder <System-drive>:\Documents and Settings\All Users\ApplicationData\Microsoft\Crypto\RSA\MachineKeys.

If the required access permission is not assigned, the ASP.NET program will not be able to use the proxies.

Starting a Standalone JVM for Proxy Use

JNBridgePro applications accessing Java classes and objects from .NET must have an installed and running Java-side. This can be either a standalone JVM, or a J2EE application server. You will find information on configuring a J2EE application server to work with JNBridgePro in the Users’ Guide. A standalone JVM must contain the JNBCore component and Java classes before generating the proxies.

To start the Java-side manually in a standalone JVM, specify the following command-line command:

java –cp classpath com.jnbridge.jnbcore.JNBMain /props propFilePath

where classpath must include the following:

• Java classes and their supporting classes for generating proxies

• jnbcore.jar

• JAR files for the XML package (if using HTTP/SOAP communication)

If the –cp classpath option is omitted, include the following information required in the CLASSPATH environment variable: propFilePath, the full file path for jnbcore .properties. The folder containing the java.exe executable must be in the system’s search path (typically described in the PATH environment variable). If not, specify the full path of java.exe on the command line.

When starting the Java-side manually, you will see the following when using the binary protocol:

JNBCore v1.2
Copyright 2002, JNBridge
creating binary server

or the following if using HTTP/SOAP:

JNBCore v1.2
Copyright 2002, JNBridge
creating http server

Running the Java-Side Under Nondefault Security Managers

The Java-side will work under the default security manager (that is, the one used if no security manager is explicitly set). If a security manager is set, permissions may need to be granted explicitly to allow jnbcore.jar to run. In the appropriate copy of the file java.policy, add the following lines:

grant codebase "file://location_of_jnbcore.jar_goes_here"
{
permission java.lang.RuntimePermission "*", "accessDeclaredMembers";
permission java.net.SocketPermission "*", "accept,resolve";
}

jnbcore will now run with all required permissions. If a security manager has been set, you may also need to grant permissions for your Java classes running on the Java-side.