Listeners are web engine channels that can be accessed by HTTP/TCP clients and web servers that follow the AJP protocol.

The following figure show the connections between the web engine listeners, each clients, and protocols.

[Figure 2.1] Web Engine Listeners

The following describes each listener.

Connectors are channels that connect to WebtoB or Tmax from the web engine.

The following figure show the connections between the web engine connectors, each clients, and protocols.

[Figure 2.2] Web Engine Connectors

The following describes each connector.

Listeners and connectors have a worker thread pool that is required to process client requests. The worker thread pool manages worker threads.

When a listener receives a request, a worker thread is allocated to process the request. For a connector, an individual connection to WebtoB or Tmax is created, and a worker thread is allocated to that connection. Since the minimum and maximum values of the worker thread pool affects the service processing performance, set appropriate min and max values when configuring listeners and connectors.

Active-Management and Status Notification

The worker thread pool contains configurations for active management.

The administrator can configure active management to allow the web engine to send a warning message via e-mail or to recommend restarting the server of the engine.

To requires configuring the number of blocked worker threads that will trigger an action like sending a warning message via e-mail or a recommendation to restart the server.

This section describes the common listener settings.

AJP listeners can be added, modified, or deleted in WebAdmin or the console tool.

Using WebAdmin

Using the Console Tool

The following shows how to add, modify, and delete AJP listeners using the console tool.

HTTP listeners can be added, modified, and deleted in WebAdmin or the console tool. Using HTTP listeners is only recommended for internal management.

Using WebAdmin

Using the Console Tool

Similar to AJP listeners, HTTP listeners can be added, modified, or deleted using the console tool. For more information, refer to "Using the Console Tool" in "2.3.2. AJP Listeners".

A TCP listener is a special listener that allows custom protocols to communicate with each other. TCP listener cannot share server listeners with other web listeners, so a dedicated listener for the TCP listener must be added to the server. TCP listeners can be added or modified in WebAdmin or the console tool.

Using WebAdmin

Using the Console Tool

Similar to AJP listeners, HTTP listeners can be added, modified, or deleted using the console tool. For more information, refer to "Using the Console Tool" in "2.3.2. AJP Listeners".

Since JEUS acts as a client when a WebtoB connector creates a connection, the address and port of WebtoB are required. WebtoB connectors can be added, modified, and deleted in WebAdmin or the console tool.

Using WebAdmin

Using the Console Tool

The following shows how to add, modify, and delete WebtoB connectors.

Like with WebtoB connectors, since JEUS functions as a client when a Tmax connector creates a connection, the address and port of Tmax are required.

Tmax connectors can be added, modified, and deleted in WebAdmin or the console tool.

Using WebAdmin

Using the Console Tool

The following shows how to add, modify, and delete a Tmax connector using the console tool.

Thread state notification setting defines the minimum number of worker threads that will trigger a notification via e-mail or to recommend restarting the server. Configure the Thread State Notify setting from the listener or connector configuration screen.

If automatic thread pool management is configured, worker threads are managed based on the 'Max Thread Active Time' value.

Threads for which the request processing time exceeds the Max Thread Active value are considered as blocked threads. If the number of threads, excluding blocked threads, is less than the minimum thread pool size, enough new worker threads are created to maintain the minimum value.

Since WebtoB connectors are not configured with a minimum value but only a total number of connections, they operate differently from other listeners and connectors. For WebtoB connectors, the sum of blocked threads and regular threads must be same as the number of connections. As soon as a blocked thread completes a request, it will be deleted and any new requests will use a new worker thread.

Thread state notifications can be configured in the thread pool to receive notifications.

The following example configures an e-mail notifier for an AJP listener. For more information about configuring an e-mail using the e-mail notifier, refer to the SMTP handler configuration in ????.

[Figure 2.32] Configuring Automatic Thread Pool Management - Thread State Notify

The following describes each configuration option.

When a web site needs to handle a large number of requests, a single web server and web engine are not sufficient in handling the requests. In such cases, multiple servers and web engines are required for load balancing.

The following diagram shows a load balancing structure in which two web servers are connected to four web engines.

[Figure 2.33] Load Balancing Structure

The same web context must be deployed to each engine. In this environment, the most important issue is whether or not the sessions are shared. Web engines must be clustered in order to manage applications more easily or if distributed sessions are required. For more information about session clustering, refer to JEUS Session Management Guide. "Chapter 1. Session Tracking".

Execute the following steps to integrate Apache with the web engines.

Installing the mod_jk Library

To use Apache web servers with web engines, the mod_jk module must be added to Apache. The mod_jk module implements the Apache JServ Protocol 1.3(AJP 1.3), a communication protocol between servers and engines.

Configuring AJP13 Listeners

After the mod_jk library has been installed, configure the AJP13 listener in the JEUS web engine. For more information about configuring AJP13 listeners, refer to "2.3.2. AJP Listeners".

Configuring the workers.properties File

The workers.properties file is a configuration file for mod_jk.

As an example, there are two JEUS servers named server1 and server2 and the host names are server1 and server2. The name of the web engine for each server is server_servelt and server2_servlet. The AJP listeners configured on each web engine are 9901 and 9902.

The following is an example of the workers.properties file in the JEUS environment.

worker.list=jeus_load_balancer_workers
worker.jeus_load_balancer_workers.type=lb
worker.jeus_load_balancer_workers.sticky_session=true

###########################################
# listener specific configuration
###########################################
worker.jeus_load_balancer_workers.balance_workers=server1
worker.server1.reference=worker.template
worker.server1.host=192.168.0.101
worker.server1.port=9901
worker.server1.route=ZG9tYWluMS9zZXJ2MQ==

worker.jeus_load_balancer_workers.balance_workers=server2
worker.server1.reference=worker.template
worker.server1.host=192.168.0.102
worker.server1.port=9902
worker.server1.route=ZG9tYWluMS9zZXJ2Mg==


###########################################
# common config
###########################################
worker.template.type=ajp13
worker.template.socket_connect_timeout=5000
worker.template.socket_keepalive=true
worker.template.ping_mode=A
worker.template.ping_timeout=10000
worker.template.connection_pool_minsize=0
worker.template.connection_pool_timeout=600
worker.template.reply_timeout=300000
worker.template.recovery_options=3

The workers.properties file uses the "worker.<worker_name>.<directive>=<value>" format to define most settings. The following describe the major configuration options.

Configuring httpd.conf

To use the mod_jk module, add the following to the httpd.conf file:

. . .
LoadModule    jk_module  "/usr/local/apache/modules/mod_jk.so"
JkWorkersFile "/usr/local/apache/conf/workers.properties"
JkLogFile     "/usr/local/apache/logs/mod_jk.log"
JkLogLevel    info
JkMount /examples/* jeus_load_balancer_workers
. . .

IIS and Iplanet support the AJP13 protocol. The workers.properties file is configured in the same way as JEUS, but mod_jk is installed and configured differently. Refer to the manual of each web server.

This section describes how to configure load balancing between WebtoB and JEUS, and provides examples.

The following shows the server structure of the example. Each engine is connected a WebtoB server. In the following example, there are two WebtoB servers and each one is connected to two web engines.

[Figure 2.34] Load Balancing Server Structure

The same context must be deployed to each server.

In general, in a structure like the previous figure, servers A through D become clustered and distributed session servers are used accordingly. Clustering is not necessary if user sessions are not used.

The following diagram shows the dotted box in detail and displays each WebtoB connector configurations.

[Figure 2.35] WebtoB Connector Configurations

When configuring WebtoB connectors, consider the number of WebtoB HTH processes.

A WebtoB HTH process functions as if it has multiple sub-processes. It is connected to a worker thread of WebtoB connector as one to one. Choose appropriate values for the WebtoB connector's 'Worker Thread Pool Max' setting and the WebtoB server's 'MaxProc' setting.

The number of HTH processes in the WebtoB configuration can be set in the 'Hth Count' setting of the WebtoB connector. The 'MaxProc' value of WebtoB and the 'Worker Thread Pool Max' value of the WebtoB connector can be expressed using the following formulas.

MinProc = 
Listener A number threads + Listener B number threads + … + Listener X number threads setting.
MaxProc = 
Listener A number threads + Listener B number threads + … + Listener X number threads setting.

The 'Hth Count' of the WebtoB connector must be the same as the number of HTH processes of the *NODE configuration in the WebtoB configuration file. For more information about configuring WebtoB connectors, refer to "2.3.5. WebtoB Connectors".

The following example of the http.m file configures WebtoB A from the previous example.

*NODE
foo     … 
   HTH = 2,
   JSVPORT = 9900,
   …   
*SVRGROUP
jsvg    NODENAME = foo, SVRTYPE = JSV
*SERVER
default    SVGNAME = jsvg, MinProc = 6, MaxProc = 25
*URI
uri1  Uri = "/examples/", Svrtype = JSV
uri2  Uri = "/test/", Svrtype = JSV
*EXT
jsp  MimeType = "application/jsp", SvrType = JSV

Note the values of min and max. The min and max values are set as in the following.

HTH MinProc = 6 = 2 thread + 4 thread, HTH MaxProc = 25 = 10 thread + 15 thread

The TCP listener divides all messages that are exchanged between TCP client and TCP handler into two parts, the header and body. In general, the header is fixed in size and contains standard information. The body contains user data, such as the HTML code in an HTTP response, to transmit.

This section defines a simple protocol (message structure) to describe how to use the TCP listener.

The custom communication protocol (custom message structure) contains the following contents.

A dispatcher configuration class is a subclass of the jeus.servlet.tcp.TCPDispatcherConfig class. The abstract method of the class must implement the information required for the TCP listener to deliver messages to the appropriate TCP handler. The methods are described in the JEUS_HOME/docs/api/jeusapi/index.html file.

Starting from JEUS v7.0 Fix #1, the getBodyLengthLong method has been added. If the TCP Body is 2GB or more, the Body length can be set to 8Byte by using this method.

The following code shows how the dispatcher configuration class is implemented based on the defined protocol. Refer to the comments to understand how the methods are used.

package sample.config;

import javax.servlet.*;
import javax.servlet.http.*;
import jeus.servlet.tcp.*;

/*
  This class extends the abstract class jeus.servlet.tcp.
  TCPDispatcherConfig class. This implementation provides
  routing and handling information to the TCP listener
  according to our defined communications protocol.
*/
public class SampleConfig extends TCPDispatcherConfig {
    /*
      Any init code goes into this method. This method will be    
      Called once after starting the TCP listener.
      We leave this method empty for our simple example.
    */
    public void init() {}

    /*
      This method returns the fixed-length of the header so                  
      that the TCP listener knows when to stop                                   
      reading the header. The header length for 
      our example is 41 (bytes): 4 (magic) + 1 
      (type) + 4 (body length) + 32 (service name).
    */
    public int getHeaderLength() {
        return 41; 
    }
    
    /*
      This method must return the length of the body.
      For our example, this length is represented as an 
      “int” in the header, starting at position “5” 
      (see the protocol definition above).
    */
    public int getBodyLength(byte[] header) {
        return getInt(header, 5);
    }

    /**)
     * Returns the long-size length of request body of
     * incoming request packet.
     * If you don't need to support long, you may map to
     * {@link #getBodyLength(byte[])}.
     */
    public long getBodyLengthLong(byte[] header) {
        return getBodyLength(header);
    }

    /*
      This method must return the context path so that the
      request can be routed by the TCP listener to the context
      that contains the TCP handler (TCPServlet implementation).
      For our example, we always use the context path “/tcptest”.
    */
    public String getContextPath(byte[] header) {
        return "/tcptest";
    }

    /*
      This method must return the name (path) of the TCP 
      handler(TCPServlet) relative to the context path. 
      For our example, we fetch this name from the 9th position
      in the header.
    */
    public String getServletPath(byte[] header) {
        return "/" + getString(header, 9, 32);
    }

    /*
      This method returns some path info from the header.
      It is not used in our example and thus returns “null”.
    */
    public String getPathInfo(byte[] header) {
        return null;
    }

    /*
      This method returns any session ID embedded in the header.
      It is not used in our example and thus returns “null”.
    */
    public String getSessionId(byte[] header) {
        return null;
    }

    /*
      This method determines whether the TCP listener 
      should keep the socket connection open after the TCP handler
      has delivered its response. If it returns “false”, the
      connection will be dropped like in HTTP communications.
      If it returns “true” the connection will be kept open
      like in the Telnet or FTP protocols. For our example,
      we choose to make it persistent (connection not closed
      by the TCP listener).
    */
    public boolean isPersistentConnection() {
        return true;
    }
}

TCP servlets are always a subclass of the jeus.servlet.tcp.TCPServlet class. The handler always contains the abstract void service(TCPServletRequest req, TCPServletResponse, res) method that is overridden.

The service method must be implemented to process messages that follow the custom protocol. The web container reads a header and sends it to the TCPServletRequest object, and the TCP servlet writes a response to an output stream of the TCPServletResponse object.

The following is an implementation of the TCP servlet that processes the message that follows the custom protocol.

package sample.servlet;

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import jeus.servlet.tcp.*;

/**
 * Sample TCPServlet implementation
 *
 * Protocol scheme:
 * 
 * common header (for request and response) : total 41 byte
 * 
 *   magic field: length = 4 byte, value = 7777
 *   type field : length = 1 byte, 0 : request, 1:response
 *   body length field : length = 4, value = 128
 *   service name field : length = 32
 * 
 * request and response body
 *  
 *   message1 field : length = 64
 *   message2 field : length = 64
 * 
 */

public class SampleTCPServlet extends TCPServlet {

    public void init(ServletConfig config) throws ServletException {
    }

    public void service(TCPServletRequest req, TCPServletResponse res)
        throws ServletException, IOException {
        ServletContext context = req.getServletContext();
        byte[] header = req.getHeader();
        byte[] body = new byte[req.getContentLength()];
        int read = req.getInputStream().read(body);
        if (read < body.length) {
            throw new IOException("The client sent the wrong content.");
        }

        String encoding = res.getCharacterEncoding();
        if (encoding == null)
            encoding = "euc-kr";

        DataInputStream in = new DataInputStream(new ByteArrayInputStream(header));
        int magic = in.readInt();
        context.log("[SampleTCPServlet] received magic = " + magic);

        byte type = (byte)in.read();
        context.log("[SampleTCPServlet] received type = " + type);

        int len = in.readInt();
        context.log("[SampleTCPServlet] received body length = " + len);

        byte[] svcname = new byte[32];
        in.readFully(svcname);
        context.log("[SampleTCPServlet] received service name = " 
                     + (new String(svcname)).trim());

        String rcvmsg = null;
        rcvmsg = (new String(body, 0, 64)).trim();
        context.log("[SampleTCPServlet] received msg1 = " + rcvmsg);

        try {
            rcvmsg = (new String(body, 64, 64, encoding)).trim();
        } catch (Exception e) {}
        context.log("[SampleTCPServlet] received msg2 = " + rcvmsg);

        String msg1 = "test response";
        String msg2 = "test response2";

        byte[] result1 = null;
        byte[] result2 = null;
        if (encoding != null) {
            try {
                result1 = msg1.getBytes(encoding);
                result2 = msg2.getBytes(encoding);
            } catch (UnsupportedEncodingException uee) {
                result1 = msg1.getBytes();
                result2 = msg2.getBytes();
            }
        } else {
            result1 = msg1.getBytes();
            result2 = msg2.getBytes();
        }

        header[4] = (byte)1; // mark as response

        ServletOutputStream out = res.getOutputStream();
        out.write(header);

        byte[] buf1 = new byte[64];
        System.arraycopy(result1, 0, buf1, 0, result1.length);
        out.write(buf1);

        byte[] buf2 = new byte[64];
        System.arraycopy(result2, 0, buf2, 0, result2.length);
        out.write(buf2);

        out.flush();
    }

    public void destroy() {
    }
}

Configure the TCP listener based on the SampleConfig.java and SampleTCPServlet.java implementations and using the following steps.

TCP clients connect to TCP listeners using a socket and uses the connection to send messages. The messages are byte streams that follow the custom protocol defined in "2.5.1. Defining Custom Communication Protocols".

The TCP listener receives the messages and calls the service() method of the SampleTCPservlet class based on dispatch information defined in the SampleConfig class. The SampleTCPServlet creates the response based on the client data and delivers it. The client receives the response and outputs it using System.out.

The following is an example of a TCP client implementation.

package sample.client;

import java.io.*;
import java.net.*;

public class Client {
    private String address;
    private int port;

    private int magic = 7777;
    private byte type = 0;
    private int bodyLength = 128;
    private byte[] serviceName="sample".getBytes();

    public Client(String host, int port) {
        this.address = host;
        this.port = port;
    }

    public void test()
        throws IOException, UnsupportedEncodingException {
        Socket socket = new Socket(address, port);
        DataOutputStream out = new DataOutputStream(
            new BufferedOutputStream(socket.getOutputStream()));
        DataInputStream in = new DataInputStream(
            new BufferedInputStream(socket.getInputStream()));

        out.writeInt(7777);
        out.write(type);
        out.writeInt(bodyLength);
        byte[] buf = new byte[32];
        System.arraycopy(serviceName, 0, buf, 0, serviceName.length);
        out.write(buf);
        byte[] msg1 = "test request".getBytes();
        byte[] msg2 = "test request2".getBytes();
        buf = new byte[64];
        System.arraycopy(msg1, 0, buf, 0, msg1.length);
        out.write(buf);
        buf = new byte[64];
        System.arraycopy(msg2, 0, buf, 0, msg2.length);
        out.write(buf);

        out.flush();

        // rx msg
        int magic = in.readInt();
        System.out.println("[Client] received magic = " + magic);

        byte type = (byte)in.read();
        System.out.println("[Client] received type = " + type);

        int len = in.readInt();
        System.out.println("[Client] received body length = " + len);

        byte[] svcname = new byte[32];
        in.readFully(svcname);
        System.out.println("[Client] received service name = " +
                           (new String(svcname)).trim());

        byte[] body = new byte[128];
        in.readFully(body);
        String rcvmsg = null;
        rcvmsg = (new String(body, 0, 64)).trim();
        System.out.println("[Client] received msg1 = " + rcvmsg);
        rcvmsg = (new String(body, 64, 64, "euc-kr")).trim();
        System.out.println("[Client] received msg2 = " + rcvmsg);

        out.close();
        in.close();
        socket.close();
    }

    public static void main(String[] argv) throws Exception {
        Client client = new Client("localhost", 5555);
        client.test();
    }
}

In the previous client code, note the various field configurations of the header that are required for the protocol.

The 'magic' number is set to '7777', the 'type' is set to '0' (request), the 'body length' is set to '128 bytes', and the 'service name' is set to 'sample', which is the name in web.xml. After creating two messages, the header information is sent and the messages are sent to the TCP listener. Finally, the 'hostname' is set to 'localhost' and the port number is set to '5555'.

Assume that the TCP listener is set to 'localhost' with the port number '5555'.

The TCP client is compiled and executed using the following steps.

HTTP/2 uses two identifiers, h2c and h2. The following table describes each identifier.

To use HTTP/2 by using h2c, no additional work is required. Simply refer to "2.3.3. HTTP Listeners", and check the relevant item.

To use HTTP/2 by using h2, additional work is requried. h2 runs by using TLS (Transport Layer Security), and must use the ALPN(Application Layer Protocol Negotiation) function during a TLS handshake process. The ALPN function is planned to be included in JDK 9, and therefore the ALPN function cannot be used in JEUS 8 (which was developed based on JDK 7). h2 runs by using TLS, so it must use a port set with a secure listener.

The following actions are required to use ALPN.

Server Push is a function in which a response is sent by a server even if a client does not send a request for a specified resource. This decreases the amount of time required for sending a request, which results in faster response.

To use the Server Push function, specify a resource to be server pushed during web application development.

The following describes how Server Push is used: a PushBuilder object is obtained, then the resource path is specified, and then the push() method is called.

Server Push gets a PushBuilder object, and then specifies the resource path, and then calls the push() method. The following is an example of using Server Push.

package sample.serverpush

...
import jeus.servlet.engine.HttpServletRequestImpl;
import jeus.servlet.engine.PushBuilder;

@WebServlet("/ServerPush")
public class ServerPushServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        
        // Change the data type of req to HttpServletRequestImpl, which is a JEUS implmentation.
        // Then,obtain the PushBuilder object.
        HttpServletRequestImpl reqImpl = (HttpServletRequestImpl)req;
        PushBuilder builder = reqImpl.getPushBuilder();
        String pushResourcePath = "resources/a.txt";
        
        // Enter the path of the resource to push and then call the push() method.
        builder.path(pushResourcePath);
        builder.push();

        resp.getWriter().write("main page\n");
    }
}