Setting up and Administering the EntireX Broker TCP Agent

The EntireX Broker TCP Agent is a gateway to the broker whenever direct TCP/IP communication with the broker is not possible. Under Windows, use the delivered batch file <drive>:\SoftwareAG\EntireX\EntireX\bin\brokeragent.bat to start the agent. This document covers the following topics:


Common Scenarios

The most common scenarios for using the Broker TCP Agent are where the Java security manager does not allow direct communication with the Broker. For example, an untrusted Java applet can only open a TCP/IP connection to a Broker which is running on the same machine as the Web server.

Although in most cases the Broker TCP Agent will be used from a Broker application written in Java, the Broker TCP Agent can also be used from any component or application configured with TCP/IP.

Indirect TCP/IP Connections by the TCP Agent to Avoid Security Restrictions

The Broker TCP Agent must be used when the Java client cannot open a TCP/IP connection to the EntireX Broker due to security or firewall settings. The most prominent case is the Java sandbox model, which permits a Java applet to open only TCP/IP connections to the machine where the Web server resides. If the EntireX Broker is running on a different machine, a TCP Agent has to be run on the Web server machine.

Using the TCP Agent

Class Name and Parameters

The Broker TCP Agent is a standalone Java application. The class name which contains the main method is com.softwareag.entirex.ba.BrokerAgent.

Specify the following parameters in the order given in this table when the TCP Agent listens on a TCP/IP port:

Parameter Explanation
1. Trace Option Valid values: ON or OFF. Default: OFF.
A dump of the buffers is written to standard output for diagnostic purposes.
2. Port Number The port number the TCP Agent uses for incoming requests from Broker applications. This port number must be specified as part of the Broker ID in the Broker application.
3. Broker Address The TCP Agent sends all requests to this Broker using any legal Broker ID defined with URL-style Broker ID. The TCP Agent will use direct TCP/IP communication if the TCP/IP protocol is used (the address is of the form Hostname, Hostname:Number or starts with tcpip://).
4. Bind Address The address of the network interface on which the Broker TCP Agent will listen for connection requests. The default is that the Broker Agent will listen on any attached interface adapter of the system. The bind address is the local IP address or host name to bind to.

Starting the TCP Agent

Under Windows, the EntireX distribution kit comes with a batch file to start the Broker TCP Agent. Change the port number and the Broker address in file <drive>:\SoftwareAG\EntireX\EntireX\bin\brokeragent.bat.

Activating Tracing for the TCP Agent

Set the parameter Trace Option to "ON". See Class Name and Parameters.

Architecture of the Broker TCP Agent

The architecture of the Broker TCP Agent is shown in the following picture:

graphics/tcpAgent_arch.png