Version 9.5 SP1
 —  EntireX Java ACI  —

Writing Advanced Applications - EntireX Java ACI

This document covers the following topics:


Using Compression

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:

Using setCompressionLevel()

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

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

Using Broker ID

You may append the keyword COMPRESSLEVEL with one of the values above to the Broker ID.

Examples

Both examples set the compression level to 9.

Top of page

Using EntireX Security with Java-based EntireX Applications

Java-based EntireX applications (including applications using classes generated by the Java Wrapper) which require security can use the security services offered by EntireX Security. See

Use the methods for security that are included in the Broker object (see Broker). The two security alternatives are

Start of instruction setTo use EntireX Security

Start of instruction setTo use your own security implementation

Top of page

Using Integrated Authentication Framework with Java-based EntireX Applications

Java-based EntireX applications (including applications using classes generated by the Java Wrapper) which require security can use the security services offered by IAF.

The methods for IAF are included in the Broker object (see Broker). If the Broker is set up for IAF, the client application can get the IAF token after logon with the method Broker.getIAFToken. The token is a byte[256] array. The content is not visible to the client. The client can use the token as-is only and must not change it. The token returned by Broker.getIAFToken can be used to authenticate the client to other products using IAF.

On the other hand, a token obtained from some other product can be used with Broker.setIAFToken to authenticate with the Broker.

The client should delete the token after Broker.logoff with Broker.setIAFToken(null).

Top of page

Setting Transport Methods

Socket Parameters for TCP and SSL Communication

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

Controlling Socket Pooling

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

Start of instruction setTo specify the maximum number of socket connections

Start of instruction setTo disable socket pooling

Start of instruction setTo control the automatic closing of socket connections

Using SSL

Java-based EntireX applications (including applications using classes generated by the Java Wrapper) can use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) as the transport medium. In this section, "SSL" refers to both SSL and TLS. Java-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the EntireX Broker Agent. SSL transport will be chosen if the Broker ID starts with the string ssl://.

Example of a typical Broker ID for SSL:

Broker broker = new Broker("ssl://yourbroker:10000?trust_store=castore","userID");

If no port number is specified, port 1958 will be used as the default port. The trust_store parameter is mandatory. It specifies the file name of a Java keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. If the server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server) two additional parameters have to be specified as part of the Broker ID:

Broker broker = new Broker("ssl://yourbroker:10000?trust_store=castore&key_store=keystore&key_passwd=pwd","userID");

Again, key_store is the file name of a Java keystore. 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.

By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. In the example above, the common name of the subject entry in the server's certificate must be identical to yourbroker. This checking can be disabled by specifying the parameter verify_server=no in the Broker ID.

Using HTTP(S) Tunneling

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:

How the Communication Works

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.

Java communication

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 HTTP(S) Agent (formerly referred to as Tunnel Servlet)) each Broker request is sent to a Web server, which immediately processes the 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 Broker HTTP(S) Agent under UNIX | Windows.

How to Enable HTTP Support in a Java Component

Start of instruction setTo enable HTTP support for a Java-based component

The 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 HTTP(S) Agent.

Start of instruction setTo enforce logging of the HTTP(S) Agent

How to Enable HTTPS Support in a Java Component

Start of instruction setTo use HTTPS instead of HTTP

Setting the Transport Timeout

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.

Start of instruction setTo specify a TCP or SSL transport timeout

  1. 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.

  2. 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().

Top of page

Tracing

Java-based EntireX applications (including applications using classes generated by the Java Wrapper) can use tracing to log program flow and locate problems.

Start of instruction setTo specify the trace level

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

Top of page

Using Internationalization with Java ACI

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 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

Top of page