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:

  • Use the method setCompressionLevel() of the Broker object.

  • Use a Broker ID with the parameter compresslevel=<value>.

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

  • 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

Using Broker ID

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

Examples

  • localhost:1971?compresslevel=BEST_COMPRESSION
  • localhost?poolsize=4&compresslevel=9

Both examples set the compression level to 9.

Using EntireX Security with Java-based EntireX Applications

Java-based EntireX applications that require security can use EntireX Security. Use one of the supported methods of useEntireXSecurity() within class Broker. See also Introduction to 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.

Notes:

  1. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.
  2. Existing user-written security exits created for earlier versions of EntireX will continue to be supported.

Setting Transport Methods

Socket Pooling Parameters for TCP and SSL/TLS Communication

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

Start of instruction setTo 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.

Start of instruction setTo disable socket pooling

  • Set the parameter poolsize (as part of the Broker ID) to "0".

Start of instruction setTo 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");

Using the Broker ACI with SSL/TLS

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 Platform-independent Administration documentation.

Start of instruction setTo use SSL

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

  2. 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");
  3. 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:

    • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

    • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

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 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 Broker HTTP(S) Agent builds the bridge between Web server and EntireX Broker in the intranet.

graphics/tunneling.png

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.

Enabling HTTP Support

Start of instruction setTo 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.

Start of instruction setTo 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");

Enabling HTTPS Support

Start of instruction setTo 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.

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

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

  • 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

Using Internationalization with Java ACI

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.

See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.