Settting 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 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 TCP Agent will be used from a Broker application written in Java, the TCP Agent can also be used from non-Java applications as long as the Broker stubs support TCP/IP.

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

The 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 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 as in EntireX Java. The TCP Agent will use direct TCP/IP communication if the address is of the form Hostname, Hostname:Number, or if it starts with tcpip://
4. Port Number for commands (optional) The port number the TCP Agent uses for incoming commands.

Starting the TCP Agent

Under Windows, the EntireX distribution kit comes with a batch file to start the 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 TCP Agent

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

Architecture of EntireX TCP Agent