This document covers the following topics:
Java-based EntireX applications (including applications using classes generated by the Java Wrapper) may compress the messages sent to and received from the Broker. There are two ways to enable compression:
Use the method setCompressionLevel() of the
Broker object.
Use a Broker ID with the parameter
compresslevel=<value>.
Add the compression level to the method
setCompressionLevel() as an integer or a string
argument.
You can use the constants defined in class
java.util.zip.Deflater.
If the string
starts with Y, compression is turned on with level 6,
starts with N, compression is turned off (level 0).
Permitted values are the integers 0 - 9 and the corresponding strings:
BEST_COMPRESSION |
level 9 |
BEST_SPEED |
level 1 |
DEFAULT_COMPRESSION |
level 6 |
DEFLATED |
level 8 |
NO_COMPRESSION |
level 0 |
You may append the keyword COMPRESSLEVEL with
one of the values above to the Broker ID.
localhost:1971?compresslevel=BEST_COMPRESSION
localhost?poolsize=4&compresslevel=9
Both examples set the compression level to 9.
Java-based EntireX applications that require security can use security offered by EntireX. The following approaches are possible:
EntireX Security, see Overview of EntireX Security for a general introduction
Broker Security, for your own security implementation. See Sample Security Exits for Broker Security.
Encryption. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.
To use EntireX Security
Use one of the supported methods of useEntireXSecurity() within class Broker. See also Overview of EntireX Security for additional prerequisites. The auto mode specifies that the Broker object uses EntireX Security as needed by the broker
kernel. If the broker kernel is set up with security, the Broker object uses EntireX Security. If the broker kernel is not
set up with EntireX Security, it is not used.
To use your own security implementation
Implement the interface BrokerSecurity. This implementation must
have an accompanying security exit for the broker kernel. See Using Sample Security Exits for Broker Security for more information.
Call one of the methods of
setSecurity() with the security object similar to
useEntireXSecurity().
Socket connections for EntireX Java ACI applications and applications using classes generated by the Java Wrapper
are assigned dynamically to instances of Broker objects. They are closed automatically when they are not used for a certain
period of time.
The behavior of the socket pooling can be controlled by two parameters
(poolsize and pooltimeout)
specified as part of the Broker ID. They are used for both TCP and SSL communications.
You can
specify the maximum number of socket connections which are kept in the socket pool
disable socket pooling
control the automatic closing of socket connections
To specify the maximum number of socket connections
Specify the parameter poolsize as part of
the Broker ID.
If the number entered is reached, further Broker calls going
through a Broker instance will be delayed until a socket becomes available. If
a multithreaded application uses blocking sendReceive or Receive calls with a
longer waiting time, the poolsize parameter must be at
least equal to the number of threads.
The value of entirex.timeout (in seconds) is used to
terminate the wait time for free sockets. If all sockets in the pool are in
use, the calls will be delayed at the most by the period of time specified by
this timeout. Afterwards, the call returns with error code 0013
0333. This is to prevent applications from hanging up if all
sockets are in use and never become available due to network problems.
The default for poolsize is 32.
The default can be changed with a Java system property.
Set the property entirex.socket.poolsize to specify a different value.
Values that are not numeric or less than 1 are ignored.
To disable socket pooling
Set the parameter poolsize (as part of the
Broker ID) to "0".
To control the automatic closing of socket connections
Specify the parameter pooltimeout (as part
of the Broker ID).
If a socket connection has not been used for the specified number of seconds, it will be closed automatically.
The default for pooltimeout is 300
seconds.
Example of a maximum number of 10 socket connections and a timeout of 60 seconds:
Broker broker = new Broker("yourbroker?poolsize=10&pooltimeout=60","userID");
ACI applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. ACI-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the Broker SSL Agent. For an introduction see SSL/TLS and Certificates with EntireX in the EntireX Security documentation.
To use SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Specify Broker ID and SSL parameters.
SSL transport will be chosen if the Broker ID starts with the string ssl://. Example of a typical URL-style Broker ID:
Broker broker = new Broker("ssl://yourbroker:10000?trust_store=castore","userID");
If no port number is specified, port 1958 is used as default.
If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter
specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of
the SSL server.
By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID.
The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the
connection will be refused.
You can disable this check with SSL parameter verify_server=no.
If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate
(the parameter verify_client=yes is defined in the configuration of the SSL server).
Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd.
This keystore must contain the private key of the SSL client. The password that protects the private key is specified with
key_passwd.
The ampersand (&) character cannot appear in the password.
SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.
Example of one-way SSL:
Broker broker = new Broker("ssl://yourbroker:10000?trust_store=castore&verify_server=no","userID");
Example of two-way SSL:
Broker broker = new Broker("ssl://yourbroker:10000?trust_store=castore&key_store=keystore&key_passwd=pwd","userID");
Make sure the SSL server to which the ACI application (client or server) connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. See:
When communicating with EntireX Broker over the internet, direct access to the EntireX Broker's TCP/IP port is necessary. This access is often restricted by proxy servers or firewalls. Java-based EntireX applications can pass communication data via HTTP or HTTPS. This means that a running EntireX Broker in the intranet is made accessible by a Web server without having to open additional TCP/IP ports on your firewall (HTTP tunneling). This section covers the following topics:
The Broker HTTP(S) Agent builds the bridge between Web server and EntireX Broker in the intranet.
The figure above shows how the communication works. In this scenario, a Java client program communicates via HTTP and EntireX Broker with an EntireX server. By using a Broker ID starting with "http://" (passing the URL of the installed Broker HTTP(S) Agent) each Broker request is sent to a Web server, which immediately processes the Broker HTTP(S) Agent, passes the contents to EntireX Broker, receives the answer and sends it back via HTTP. For the two partners (client and server) it is transparent that they are communicating through the Web. Java server programs can also communicate via HTTP if necessary.
For the configuration, see Settting up and Administering the EntireX Broker HTTP(S) Agent under UNIX | Windows.
To enable HTTP support
Pass the URL of your Broker HTTP(S) Agent installation as Broker ID to your Broker objects.
For Example:
import com.softwareag.entirex.aci.Broker;
...
// "http://www.yourhost.com/servlets/tunnel" is the URL to reach your broker over HTTP
Broker broker = new Broker("http://www.yourhost.com/servlets/tunnel","userID");
...
// other code not affected
...
The Broker HTTP(S) Agent optionally accepts parameters as part of the URL. It is possible to define values for Broker and log that override the corresponding values in the configuration of the Broker HTTP(S) Agent.
To enforce logging of the Broker HTTP(S) Agent
Type, e.g. the following:
Broker broker = new Broker("http://www.yourhost.com/servlets/tunnel?log=yes","userID");
To use HTTPS instead of HTTP
Replace "http://" by "https://" at the beginning of the Broker ID.
Using HTTPS requires a Web server with SSL support enabled. Check your Web server's documentation for information on how to configure SSL support.
Many Java implementations do not support HTTPS. If this is the case, your application will receive a BrokerException with error code 00130325.
Java-based EntireX applications (including applications using classes generated by the Java Wrapper) can set a transport timeout to abort socket connections when not receiving any reply.
To specify a TCP or SSL transport timeout
Use the system property
entirex.timeout.
The default is 20 seconds.
A numeric value of 1 or greater indicates the transport timeout in seconds.
Setting the value to 0 results in a potentially infinite wait (i.e. until the Broker returns a reply or the socket connection is closed).
If the Broker call is a send call with wait or a receive call, the transport timeout is added to the Broker wait time specified as part of the Broker call.
The value of entirex.timeout is used as
a timeout for waiting for free sockets in the socket pools. If the application
does not get a free socket during this timeout period, an exception will be
thrown.
Use the static method Broker.setTransportTimeout(int
timeout) in your application.
This method sets the socket timeout value in seconds. It is used for TCP/IP, but not with HTTP. The timeout value is used for new sockets, it does not change the timeout for sockets in use.
To query the current setting, use the method
Broker.getTransportTimeout().
Java-based EntireX applications (including applications using classes generated by the Java Wrapper) can use tracing to log program flow and locate problems.
To specify the trace level
Use the setTrace() method of class Broker.
Or:
Use the Java system property
entirex.trace. The system property uses the same
values as the setTrace method call.
| Trace level | Explanation |
|---|---|
| 0 | no tracing, default. |
| 1 | trace all Broker calls and other major actions |
| 2 | dump the send and receive buffer |
| 3 | dump the buffers sent to the Broker and received from the Broker |
The encoding configured for the Java virtual machine (JVM) is used to convert the Unicode (UTF-16) representation within Java to the encoding sent to or received from the broker by default. This encoding is also transferred as the codepage to the broker to tell the broker the encoding of the data. Changing the default encoding of the JVM has the side effect that the encoding for terminal and file IO is affected too. This may be undesired.
With the codepage parameter you can override the encoding without the need to change the default encoding of the JVM. The codepage must be supported by your JVM. For a list of valid encodings, see Supported Encodings in your Java documentation.
Note:
See your JVM documentation for how to change the default encoding of the JVM.
On some JVM implementations, it can be changed with the file.encoding property.
On some UNIX implementations, it can be changed with the LANG environment variable.
With the setCharacterEncoding(enc) method of the
BrokerService (EntireX Java ACI) you can override the encoding used for the payload sent to / received from the broker without affecting the default encoding
of your JVM.
Methods of the Java ACI are inherited by the Java Wrapper when programming RPC clients.
Thus, regarding character conversion, most of what is valid for the Java ACI is also valid for Java-based RPC clients,
but EntireX Broker configuration is different:
use the service-specific attribute CONVERSION to enable correct character conversion in the broker.
For Java-based RPC clients communicating with RPC-based Components and Reliable RPC, set CONVERSION=SAGTRPC.
For Java ACI clients and servers using ACI-based Programming, set set CONVERSION=SAGTCHA.
See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.