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.
An example of EntireX Security can be found in the
Client.java source in the Java ACI examples. Set the
constant field SECURITY to true, support a
password to the logon method and compile the source.
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().
Java-based EntireX applications (including applications using classes generated by the Java Wrapper) up to version 5.3.1 use one socket connection for each instance of the Broker class.
Starting with EntireX version 6.1.1, a pool of socket connections is managed by the EntireX Java runtime.
Socket connections are
assigned dynamically to instances of Broker objects
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. Starting with EntireX version 7.1.1.60,
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".
The behavior is then identical to that of the pre-6.1.1 versions of EntireX.
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 in the 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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the 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 EntireX Clients and Servers.
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 (including applications using classes generated by the Java Wrapper) 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 EntireX Java ACI is able to send and receive data via an HTTP
protocol controlled by constructor
com.softwareag.entirex.aci.Broker. See
How to Enable HTTP Support in a Java Component.
The EntireX Java component
com.softwareag.entirex.aci.TunnelServlet.class
implements a Java servlet for servlet-enabled Web servers. It 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 (formerly referred to as Tunnel Servlet)) 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 for a Java-based component
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 |
It is assumed that you have read the document Internationalization with EntireX and are familiar with the various internationalization approaches described there.
EntireX Java components use the codepage configured use the codepage configured for the Java virtual machine (JVM) to convert the Unicode (UTF-16) representation within Java to the multibyte or single-byte encoding sent to or received from the broker by default. This codepage is also transferred as part of the locale string to tell the broker the encoding of the data if communicating with a broker version 7.2.x and above.
To change the default, see your JVM documentation.
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.
Which encodings are valid depends on the version of your JVM. For a list of valid encodings, see Supported Encodings in your Java documentation. The encoding must also be a supported codepage of the broker, depending on the internationalization approach.
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. Instead of using the default JVM encoding, the given encoding is used. Using this method does not change the default encoding of your JVM.
force a locale string to be sent if communicating with broker version 7.1.x and below. Use the value LOCAL to send the default encoding of the JVM to the broker. See Using the Abstract Codepage Name LOCAL.