Web Engine

This chapter describes the components and major functions of JEUS web engine and how to configure it.

1. Overview

Jakarta EE web applications (hereafter web applications) consist of dynamic web content such as servlets and JSPs, and static resources such as HTML files. TmaxSoft provides JEUS web engine to efficiently handle these web applications.

This chapter introduces the JEUS web engine and describes how to control and monitor it in a production environment.

2. Components

This section explains the components of JEUS web engine and the external resources that interact with the engine.

Web engine is an object that manages and runs web applications that conform to the Jakarta EE, servlet, JSP, and EL standards. It can handle dynamic resources like servlets and JSPs, and static resources like HTML.

figure basic components of jeus web engine

Web Engine Components

A web engine is also known as a web container or a servlet engine.

The following are the major web engine components.

Web Connections

Web connections allow web engines to connect to client programs, web servers, and other servers.

A large cluster of web servers and web engines is configured by using web connections to improve performance and reliability. For more information, refer to Web Connection Management.
Virtual Host

A virtual host allows client programs to call web applications by host name. A web application can be deployed to a particular virtual host. For more information, refer to Virtual Hosts.
Web Context(Web Application)

When a web application is deployed to a web engine, a web context is created. Web applications are typically packaged as a web archive (WAR) file and deployed to a virtual host in the web engine. For more information, refer to Web Contexts.
Monitoring Thread

Monitoring threads monitor multiple components of the web engine. For more information, refer to Major Functions.
Session Management Service

The session management service provides an environment to manage client sessions in a distributed environment and to use the client sessions in multiple web engines. For detailed information, refer to Session Tracking in JEUS Session Management Guide.
Other Web Engine Configurations

These include configurations that apply to all web engines such as default error page configurations, encoding configurations, JSP engine configurations, and response header configurations.

The context group that was used in JEUS 6 and earlier is no longer used from JEUS 7 onwards. Most of the context group functions are provided by the web engine.

The following are the external resources that interact with web engines.

Clients

Clients send service requests to JEUS web engines, typically through an HTTP-based web browsers.
Web Servers

Web servers send client HTTP requests to a JEUS web engine. JEUS web engines typically work with web servers to handle the HTTP client requests. For more information, refer to Web Connection Management.

3. Major Functions

The following are the major functions of a web engine.

Managing web applications

Web engines can deploy, undeploy, and suspend web applications that conform to the Jakarta EE standards. Web engines can also redeploy web applications while the applications are running to provide seamless service. For more information, refer to Web Contexts.

Monitoring

Web engines monitor resource states to respond if problems occur. There are three types of monitoring. For more information about configuring each monitoring type, refer to Monitoring.

Term	Description
Thread pool monitoring	Monitors thread pools at different levels, such as Web Connection, VirtualHost, Context. For more information, see Web Connection Management.
Class loader monitoring	Monitors modifications made to servlet classes in web applications. For more information, see Web Contexts.
Session service monitoring	Checks and removes expired client sessions. For more information about session service monitoring, refer to Session Tracking in JEUS Session Management Guide.

Term

Description

Thread pool monitoring

Monitors thread pools at different levels, such as Web Connection, VirtualHost, Context. For more information, see Web Connection Management.

Class loader monitoring

Monitors modifications made to servlet classes in web applications. For more information, see Web Contexts.

Session service monitoring

Checks and removes expired client sessions. For more information about session service monitoring, refer to Session Tracking in JEUS Session Management Guide.

Default error page

Web engines can set the default error page that will be shown if the context is not ready. For more information about this configuration, refer to Default Error Page.
Attaching the stack trace

Web engines can configure the option to attach the stack trace when an error occurs. For more information about this configuration, refer to Stack Trace Attachment.
Encoding

Web engines configure the encoding that applies to all registered contexts. For more information about the configuration, refer to Encoding.
JSP engines

A JSP engine is created for each web application. When clients request JSP resources, the JSP engine converts the JSP pages to Java files, and then compiles the Java files to create the servlet byte code. This process creates Java files, used for debugging jsp files, and class files for each JSP. For more information about this configuration, refer to Configuring JSP Engines.
Response headers

Web engines can configure name-value pairs for user defined HTTP response headers. If a response header is set, the defined header will be included in all responses from the web engine. For more information about this configuration, refer to Response Headers.
Managing sessions

Web engines can configure session management. All configurations related to sessions such as clustered session participation, session object sharing, session cookie configuration, and timeouts can be set. For more information about the configurations, refer to Sessions and JEUS Session Management Guide's Session Tracking.

Event Logging

Web engines create server logs and access logs. Web applications create user logs using servlet context log method.

Term	Description
Server logs	Web engine operation logs.
Access logs	Request and result logs.
User logs	Logs that were created in web applications through the jakarta.servlet.ServletContext.log(String msg) or jakarta.servlet.ServletContext.log(String msg, Throwable t) methods.

Term

Description

Server logs

Web engine operation logs.

Access logs

Request and result logs.

User logs

Logs that were created in web applications through the jakarta.servlet.ServletContext.log(String msg) or jakarta.servlet.ServletContext.log(String msg, Throwable t) methods.

For information about the default paths to JEUS logs, refer to Directory Structure. For more information about the log configuration, refer to Logs.

Graceful Shutdown

This function guarantees the completion of running services if an administrator shuts down a JEUS server. If the administrator executes the shutdown command, the following two actions occur:

The server will no longer receive requests.
Services that are already running will complete and then shutdown will continue.

If the services that are already running take too long to complete, JEUS can set the timeout option when running the shutdown command. For more information about graceful shutdown, refer to Shutting Down a Managed Server in JEUS Server Guide.

The shutdown-timeout configuration that was provided by JEUS 6 is no longer available. Instead, the same function is provided if the shutdown timeout option is configured through the console tool (jeusadmin).

Handling web attacks

Web engines provide settings that prevent attacks like denial of service (DoS).

The limits for the POST request size, the number of parameters included in GET and POST requests, the number of headers included in a request, the size of headers included in a request, and the query string size of a GET request can be configured. For more information about these settings, refer to Preventing Web Attacks.

4. Management Tools

This section describes the tools that control and monitor web engines.

4.1. Types of Tools

The following are the web engine tools.

Console tool (jeusadmin)

A tool for controlling web engines through the console. This tool provides basic control and monitoring functions. For more information about the console tool, refer to Controlling and Monitoring JEUS Servers in JEUS Server Guide, and Web Engine Commands in JEUS Reference Guide.

4.2. Controlling and Monitoring

Tools can be used to control and monitor the web engine.

Controlling Web Engine

Controlling a web engine includes starting and shutting down the engine. This can be accomplished by using the console tool.

Using the console tool

Web engines are part of JEUS servers and there is no way to control web engines independently from the servers. For more information, refer to Controlling and Monitoring JEUS Servers in JEUS Server Guide.

Monitoring Web Engine

The console tool can be used to monitor web engines.

show-web-statistics [-server <server-name>]
                    [-ctx,--context <context-name>]
                    [-r,--request | -s,--session | -t,--thread |
                    -m,--memory]

You can use jeusadmin to view basic information about web engines. For more information about jeusadmin, refer to JEUS Server Guide and Web Engine Commands in JEUS Reference Guide.

5. Directory Structure

The following is the directory structure of JEUS web engines.

{JEUS_HOME}
   |--domains
        |--domains1
        |    |--config
        |         |--[X]Domain.xml
        |         |--Servlet
        |              |--server1
        |              |    |--[X]web.xml
        |              |    |--[X]webcommon.xml
        |              |--[X]web.xml
        |              |--[X]webcommon.xml
        |--servers
              |--server1
                   |--logs
                        |--[T]jeusServer.log
                        |--serevlet
                             |--vhost
                             |   |--[T]access.log
                             |--[T]access.log

* Legend
- [01]: binary or executable file
- [X] : XML document
- [J] : JAR file
- [T] : Text file
- [C] : Class file
- [V] : java source file
- [DD] : deployment descriptor

JEUS_HOME

JEUS installation home directory.

domains/domain1/config/

The domains directory in JEUS_HOME contains a directory for each domain name. The web engine configuration files are in the config directory, and domain1 is an example for a domain name. From JEUS 7 onwards, WEBMain.xml is no longer used. There is a separate web engine for each server JVM, so a configuration directory for each engine is not needed.

Directory / File	Description
domain.xml	Integrated configuration file that contains all server configurations for the domain. Web engines can also be configured by each server. For more information about domain.xml, refer to JEUS Server Guide.
servlet/	This directory contains the XML configuration file that is used by all servers in the domain when deploying web applications. When servers in the domain start, they receive web.xml and webcommon.xml from the Domain Administration Server to maintain synchronization. web.xml: For Servlet 3.0 and later, web.xml is not needed. But because Tomcat Jasper, a JSP parser, checks the application version based on the file, the file must be kept. Web applications that do not contain web.xml will also use this file. webcommon.xml: Shared configuration file that applies to all web applications. The file type is same as web.xml.
servlet/server1/	If webcommon.xml and web.xml exist in the servlet configuration directory, the files only apply to that server. This configuration has a higher precedence than those in the parent directories. If web.xml or webcommon.xml exists in a server directory, they are not managed automatically by JEUS, so the server administrator must manage the files manually.

Directory / File

Description

domain.xml

Integrated configuration file that contains all server configurations for the domain. Web engines can also be configured by each server. For more information about domain.xml, refer to JEUS Server Guide.

servlet/

This directory contains the XML configuration file that is used by all servers in the domain when deploying web applications. When servers in the domain start, they receive web.xml and webcommon.xml from the Domain Administration Server to maintain synchronization.

web.xml: For Servlet 3.0 and later, web.xml is not needed. But because Tomcat Jasper, a JSP parser, checks the application version based on the file, the file must be kept. Web applications that do not contain web.xml will also use this file.
webcommon.xml: Shared configuration file that applies to all web applications. The file type is same as web.xml.

servlet/server1/

If webcommon.xml and web.xml exist in the servlet configuration directory, the files only apply to that server. This configuration has a higher precedence than those in the parent directories.

If web.xml or webcommon.xml exists in a server directory, they are not managed automatically by JEUS, so the server administrator must manage the files manually.

domains/domain1/servers/server1/logs

All files created while each server in the domain is running are located in the directory created with the server’s name, under the servers directory. For more information, refer to Logging in JEUS Server Guide.

Log files are created in the logs directory. Logs created by web engines are stored in JeusServer.log. The file name can change due to log rotation, but it is initially set to JeusServer.

Directory / File	Description
servlet/	This directory contains the web application access log, access.log. If access logs are created by each virtual host in this directory, directories will be created with the virtual host names and the access logs will be stored in the corresponding directory. For more information, refer to Virtual Hosts. This directory also contains the user.log or user_appname.log file that contains logs created through the log method of the ServletContext API. User logs can be stored in user.log or in a separate file, user_appname.log, depending on the configuration.

Directory / File

Description

servlet/

This directory contains the web application access log, access.log. If access logs are created by each virtual host in this directory, directories will be created with the virtual host names and the access logs will be stored in the corresponding directory. For more information, refer to Virtual Hosts.

This directory also contains the user.log or user_appname.log file that contains logs created through the log method of the ServletContext API. User logs can be stored in user.log or in a separate file, user_appname.log, depending on the configuration.

6. Environment Configurations

This section describes environment and web engine configuration files.

Settings for the web engine can be configured using domain.xml.

Web Engine Configuration

You can configure the web engine in domain.xml.

<web-engine>
    ...
    <jsp-engine>...</jsp-engine>
    <web-connections>
        <http-listener>
            <name>SERVER-HTTP</name>
            <thread-pool>
                <min>10</min>
                <max>20</max>
                <max-idle-time>300000</max-idle-time>
                <max-queue>-1</max-queue>
            </thread-pool>
            <postdata-read-timeout>600000</postdata-read-timeout>
            <max-post-size>-1</max-post-size>
            <max-parameter-count>-1</max-parameter-count>
            <max-header-count>-1</max-header-count>
            <max-header-size>8192</max-header-size>
            <max-querystring-size>8192</max-querystring-size>
            <server-access-control>false</server-access-control>
            <allowed-server>...</allowed-server>
            <server-listener-ref>http-server</server-listener-ref>
        </http-listener>
    </web-connections>
    <monitoring>...</monitoring>
    <access-log>...</access-log>
    <ejb-engine>...</ejp-engine>
    <jms-engine>...</jms-engine>
    <system-logging>...</system-logging>
    ...
</web-engine>

6.1. XML Configuration Files

The following XML configuration files are related to web engines.

domain.xml (jeus-domain.xsd)

Location

JEUS_HOME/domains/<domain-name>/config

Purpose

JEUS web engine configurations

Details

JEUS Server Guide
jeus-web-dd.xml (jeus-web-dd.xsd)

Location

<packaged web application>/WEB-INF/

Purpose

JEUS web module deployment descriptor (DD)

Details

Described in this guide
web.xml (web-app_5_0.xsd)

Location

<packaged web application>/WEB-INF/

Purpose

Jakarta EE standard web module DD

Details

Servlet 5.0 specification
web.xml (web-app_5.0.xsd)

Location

JEUS_HOME/domains/<domain-name>/config/servlet

Purpose

Web.xml for web modules without a separate copy of web.xml

Details

Servlet 5.0 specification
webcommon.xml (web-app_5_0.xsd)

Location

JEUS_HOME/domains/<domain-name>/config/servlet

Purpose

Shared configuration file that applies to all web modules in the web engine.

Details

Servlet 5.0 specification

XML schema files are located in the JEUS_HOME/lib/schemas/jeus/supportLocale/ko/ directory. These files must start with the XML header defined by JEUS. The root element must specify the namespace of the JEUS XML schema with the existing namespace.

The following are the headers used by each file. The XML header in web.xml is included in the servlet specification.

XML header in domain.xml

<?xml version="1.0" encoding="UTF-8"?>
<domain xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="9">

XML header in jeus-web-dd.xml

<?xml version="1.0" encoding="UTF-8"?>
<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="9">

XML header in web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="5.0" xmlns="https://jakarta.ee/xml/ns/jakartaee">

All tags used in this guide are written in the same order as the XML schema. Since it is not easy to maintain the order, JEUS provides a sorting function that automatically orders the tags. Users do not need to maintain the order when editing an XML configuration file. For more information about the configuration order, refer to "JEUS XML Reference".

In the previous examples, the standard header is omitted for readability. Actual XML configuration files contain the standard header.

6.2. Monitoring

Web engines can monitor the changes of threads, classes, and sessions. Web engines can also change the monitoring interval.

The following shows how to configure the monitoring interval using domain.xml.

<web-engine>
    ...
     <monitoring>
        <check-thread-pool>300000</check-thread-pool>
        <check-class-reload>300000</check-class-reload>
        <check-session>300000</check-session>
    </monitoring>
    ...
</web-engine>

The following describes each option.

Item	Description
Check Thread Pool	Interval for checking worker thread states in the worker thread pool. The default value is 300000 (5 minutes).
Check Class Reload	Interval for checking if each class has been modified for automatic web context reloading. This configuration is used when <auto-reload><enable-reload> in jeus-web-dd.xml is configured. This does not check web applications for which <check-on-demand> is set to true.
Check Session	Interval for checking the timeout state of each session. The timeout states of sessions are defined in the web.xml file of the web engine or context. The default value is 300000 (5 minutes).

Item

Description

Check Thread Pool

Interval for checking worker thread states in the worker thread pool.

The default value is 300000 (5 minutes).

Check Class Reload

Interval for checking if each class has been modified for automatic web context reloading.

This configuration is used when <auto-reload><enable-reload> in jeus-web-dd.xml is configured. This does not check web applications for which <check-on-demand> is set to true.

Check Session

Interval for checking the timeout state of each session. The timeout states of sessions are defined in the web.xml file of the web engine or context. The default value is 300000 (5 minutes).

Since monitoring configurations except the Min/Max settings for the thread pool cannot be applied dynamically, you need to restart the server to apply the changes.

6.3. Default Error Page

When a web context exists for a request, the web context handles any errors that occur. However, if a web context does not exist, the web engine must handle the error by displaying an error page. In this case, since the default error page might not be in a form suitable for the user, the absolute path to the desired error page can be configured on the web engine.

This configuration is only used for HTTP responses. Only HTML or HTM files can be used, and forwarding is not allowed.

The following explains how to configure the default error page using domain.xml.

Specify the absolute path to the default error page in the 'Default Error Page' field.

<web-engine>
    <default-error-page>/jeus/user/error.html</default-error-page>
</web-engine>

Since the default error page setting cannot be applied dynamically, you need to restart the server to apply the setting.

6.4. Stack Trace Attachment

This configuration determines whether to display details about the error on the default error page provided by JEUS if an error occurs while a web engine is processing a request. The stack trace details are useful in a development environment, but it is not recommended to display them to the user in the production environment. The configuration can be set in jeus-web-dd.xml of each application. For more information about configuring jeus-web-dd.xml, refer to jeus-web-dd.xml Configuration.

The following explains how to configure the option to attach the stack trace in case of an error using domain.xml.

The default value is false. When set to true, Stack Trace is displayed in the default error page. However, if the 'Default Error Page' is specified, the error page is printed as configured. For more information about the default error page configuration, refer to Default Error Page.

<web-engine>
    ...
    <attach-stacktrace-on-error>false</attach-stacktrace-on-error>
    ...
</web-engine>

Since the stack trace attachment cannot be applied dynamically, you need to restart the server to apply the setting.

6.5. Encoding

There are three types of encoding configurations that can be used by all contexts in the engine. They can be applied to each application, virtual host, or server by using jeus-web-dd.xml. The XML configurations are applied in the aforementioned order. The administrator can set the encoding in domain.xml. Since encoding configuration can vary depending on each web application, it is recommended to set it in jeus-web-dd.xml. (The following XML is a configuration for jeus-web-dd.xml or domain.xml.)

Request Encoding

The encoding that is applied to query strings and cookies in the HTTP request header, and the HTTP body.
- Query strings in HTTP request lines are encoded in the following order. Query strings described to process forward and include in a Servlet or JSP are also encoded in the same order.
  1. The "forced" encoding of request-url-encoding> set in xml.
  2. The "forced" encoding of <request-encoding> set in xml.
  3. The "client-override" encoding of <request-encoding> set in xml.
  4. The "default" encoding of <request-url-encoding> set in xml.
  5. The "encoding" encoding of <url-mapping> in <request-encoding> set in xml
  6. The "default" encoding of <request-encoding> set in xml.
  7. ISO-8859-1
- Cookies in HTTP request headers are encoded in the following order of priority.
  The "charset-encoding" value of <cookie-policy><write-value-on-header-policy> that is set in xml.
  
  The "forced" encoding of <request-encoding> set in xml.
  
  The "client-override" encoding of <request-encoding> set in xml.
  
  The "encoding" encoding of <url-mapping> in <request-encoding> set in xml
  
  The "default" encoding of <request-encoding> set in xml.
  
  ISO-8859-1
  The same precedence order is applied to the cookies of the HTTP Response header. To consistently configure cookie encoding, it is recommended to set the same value to "charset-encoding" described in 1. for all web engines.
- HTTP Bodies are encoded in the following order of priority.
  The "forced" encoding of <request-encoding> set in xml.
  
  The Servlet/JSP application configuration, which is set through request.setCharacterEncoding().
  
  The "client-override" encoding of <request-encoding> set in xml.
  
  The encoding that is set by charset in Content-Type of the HTTP request.
  
  The "encoding" encoding of <url-mapping> in <request-encoding> set in xml
  
  The "default" encoding of <request-encoding> set in xml.
  
  The encoding of <request-character-encoding> set in web.xml.
  
  ISO-8859-1
  If a request is POST and Content-Type is application/x-www-form-urlencoded, a web engine will read the body and process parameters when a web application calls ServletRequest.getParameter().
  
  Note that since ServletRequest.getParameter() also processes URI query strings, if encoding set in <request-url-encoding><forced> is different from that in <request-encoding>, String objects to which different encodings are applied can be returned.
  
  Bodies are encoded when ServletRequest.getReader() is called.
The request encoding precedence order is different from JEUS 6 and 7 (earlier than Fix#1). Hence, the encoding configuration must be modified according to the previous order or compatibility options must be applied in applications where HTTP request encoding was processed in existing version.

The "forced" option has a higher precedence than the ServletAPI starting from JEUS 7 Fix #2. The client-override configuration must be used to keep the "forced" configuration in Fix #1 or earlier.

Response Encoding

The encoding that is applied to a body of HTTP response messages.

Response encoding decides which encoding to use for web container responses when converting ServletOutputStream.println() or PrintWriter.println() to a byte array, setting the "XXX" value of "Content-Type:text/html;charset=XXX" in the HTTP header, etc. It can also be set in jeus-web-dd.xml.

The response encoding is applied in the following order of priority.

The "forced" encoding of <response-encoding> set in xml.
The encoding by the JSP Response Character Encoding API call.
The "default" encoding of <response-encoding> set in xml.
The encoding of <response-character-encoding> set in web.xml
ISO-8859-1

JSP page encoding is for JSP files. However, <response-encoding><forced> is used for JSP file encoding because JSP page encoding and JSP response encoding are rarely used differently. If BOM exists in a JSP file, UTF-8 is used.

<response-encoding><forced> replaces JSP page encoding to help JSP developers to correct an invalid pageEncoding value described in a page tag only by configuring JEUS. For example, when EUC-KR is set for JSP files and pageEncoding is set to UTF-8, this issue can be resolved by setting <response-encoding><forced> to EUC-KR.

To put it simply, the following precedence order is used to read a JSP file.

BOM > <response-encoding><forced> > JSP Page Character Encoding > JSP Response Character Encoding > default

For detailed information about the JSP Page Character Encoding and Response Character Encoding, refer to the JSP standard.

Using domain.xml

The encoding can be set in domain.xml using the following ways.

In the <Encoding> section, enter the settings values for the '<request-encoding>', '<request-url-encoding>', and '<response-encoding>' tags. Except for '<request-url-encoding>', the configuration can also be set in jeus-web-dd.xml. For each item, select 'Default', 'Forced', or 'Client Override', and enter the encoding name.

<web-engine>
    ...
    <encoding>
        <request-encoding>
            <client-override>...</client-override>
        </request-encoding>
        <request-url-encoding>
            <default>...</default>
        </request-url-encoding>
        <response-encoding>
            <default>...</default>
        </response-encoding>
    </encoding>
    ...
</web-engine>

Value	Description
Default	Specifies the default encoding to use if no encoding is specified.
Client Override	Indicates to use the charset of the Content-Type header sent by the client to use if no encoding is specified.
Forced	Indicates to use a specific encoding at all times.

Value

Description

Default

Specifies the default encoding to use if no encoding is specified.

Client Override

Indicates to use the charset of the Content-Type header sent by the client to use if no encoding is specified.

Forced

Indicates to use a specific encoding at all times.

Character Encoding Configuration and Compatibility Guide

JEUS provides encoding configuration in XML to provide application developers with the ease of development and application users or administrators with ease of management. However, in the process of determining and implementing the encoding policy, there arose problems such as the mismatch of "forced" configuration definition between the request and response encodings or the violation of the servlet standard.

Starting from JEUS 7, efforts have been made to improve the consistency and correctness of the encoding policy. This may cause compatibility issues with existing applications. This guide will help modify applications or to use the compatibility option to maintain operation. It is recommended to configure the compatibility option in jeus-web-dd.xml. If it is configured in domain.xml of each server, it affects all applications deployed to the server.

Request Url Encoding
- Starting from JEUS 7, the Accept-Language Header of an HTTP Request is not referenced, and no compatibility option is provided for this.
- The forced encoding of <request-url-encoding> is used only to process query strings included in a request URL as parameters.
- When a Servlet calls ServletRequest.getParameter() for POST requests (Content-Type: application/x-www-form-urlencoded), it must be determined whether to use the forced encoding of <request-url-encoding> according to whether a query string will be processed after included in an HTTP body or will be recognized as an HTTP header.
  
  To process a query string as an HTTP body, set the forced encoding. To process a query string as an HTTP header, do not set the forced encoding. In the case of GET requests, the forced encoding of <request-url-encoding> must be set because only query strings that are included in a request URL are processed as parameters.
- Query strings become parameters when a Servlet first calls ServletRequest’s parameter API.
Request Encoding
- Applied to query strings, cookies, and request bodies.
- If forced is configured for <request-url-encoding><forced>, query strings are not affected.
- For cookies, top precedence is given to charset-encoding configuration in <cookie-policy><write-value-on-header-policy>. The jeus.servlet.request.cookie.encoding and jeus.servlet.urldecode.cookie settings used in JEUS 6 and earlier versions are no longer supported.
- If <request-encoding><forced> is used in a version earlier than JEUS 7 Fix#2, it is replaced by <request-encoding><client-override>.
- The problem with request.setCharacterEncoding() in JEUS 6 is that it applies encoding to the HTTP body as well as query strings and cookies. But the servlet standard limits the API to be applied to only the HTTP body. This is no longer an issue in JEUS 7. To use the API in JEUS 6, the jeus.servlet.request.6CompatibleSetCharacterEncoding property must be set to true, and it is recommended to set it in jeus-web-dd.xml for the relevant application.
- It is not recommended to configure <request-encoding><forced>.
  
  Web application developers do not need to call request.setCharacterEncoding() whenever writing a program if client-override of default is set. String objects can be directly created by passing an encoding value to new String() as in the following example.
  String param = request.getParameter(); String realParam = new String(param.getBytes("ISO-8859-1"), "EUC-KR");
  In the above example, to create the param object with ISO-8859-1, the default encoding (ISO-8859-1) must be set in a web engine. The realParam String object is created by a web application through JVM without a web engine.
- From JEUS 7 Fix#4 onwards, <request-encoding><url-mapping> is added in jeus-web-dd.xml.
  
  <request-encoding> in jeus-web-dd.xml replaces <request-encoding> in domain.xml.
  <request-encoding> in jeus-web-dd.xml replaces <request-encoding> in domain.xml.
  
  If only <url-mapping> is set, only requests specified in <servlet-path> are encoded. Requests that are not specified in <servlet-path> are encoded by ISO-8859-1, the Servlet standard.
  
  If <url-mapping> and <default> are set together, requests that are not specified in <servlet-path> are encoded by using the setting in <default>.
  
  Setting in <request-url-encoding><forced> of domain.xml is only applied to POST bodies.
  
  <request-encoding><url-mapping> has lower priority than the charset of a Count-Type header sent by a client.
  Request Encoding Configuration in <jeus-web-dd.xml>
  <?xml version="1.0" encoding="UTF-8"?> <jeus-web-dd> <encoding> <request-encoding> <url-mapping> <servlet-path>/test/test1</servlet-path> <encoding>EUC-KR</encoding> </url-mapping> <url-mapping> <servlet-path>/test/*</servlet-path> <encoding>UTF-8</encoding> </url-mapping> <url-mapping> <servlet-path>*.jsp</servlet-path> <encoding>EUC-KR</encoding> </url-mapping> </request-encoding> </encoding> </jeus-web-dd>
Response Encoding
- Applied to the response bodies.
- Cookies are not affected by the response encoding. charset-encoding setting in <cookie-policy><write-value-on-header-policy> is a top priority.
- The <response-encoding><forced> option has a higher precedence than response.setCharacterEncoding(), setContentType(), and setLocale(). However, the precedence in applying the "forced" option is not defined in JEUS 6 up to JEUS 7 Fix#1. This resulted in incorrect implementations, and in order to continue to use the applications that use these operations, the jeus.servlet.response.6CompatibleForcedEncoding property must be set to true. It is recommended to set the property in jeus-web-dd.xml for a corresponding application.
- Until JEUS 6, if "forced" is configured, response.setCharacterEncoding() has the top precedence. If a user still wants to maintain this operation, the jeus.servlet.response.6CompatibleSetCharacterEncoding property must be set to true. It is recommended to set the property in jeus-web-dd.xml for a corresponding application.
- It is not recommended to configure <response-encoding><forced>.
  
  Web application developers can avoid having to configure encoding every time by using the default option. If the default configuration fails to work, the response encoding must be configured using the response API.
JSP
- According to the JSP standard, JSP has two kinds of character encoding, the page character encoding and the response character encoding.
- The page character encoding is used for reading JSP files from the file system. This can be clearly distinguished from the response character encoding. Even though the file’s encoding is UTF-8, the HTTP response created from executing the JSP file can be sent as EUC-KR. However, the response character encoding must be referenced if the page character encoding is unknown. If the response character encoding is also unknown, read the file using ISO-8859-1. Refer to the JSP standard for the precedence of the page character encoding. In most cases, it is preferable to clearly set it for each JSP file as in the following.
  Page Character Encoding Configuration in <sample.jsp>
  <%@ page pageEncoding="UTF-8"%>
- The response character encoding is the charset value written in the contentType property of <page>. If this value does not exist, the page character encoding is used. If the page encoding is also unknown, there is no default value specified in the JSP standard and it is determined by the configuration or operation of the web container.
  Response Character Encoding in <sample2.jsp>
  <%@ page contentType="text/html; charset=UTF-8"%>
- It is recommended to set both of the previous values. If a user wants to apply then in a batch, add the following configurations to web.xml.
  Page and Response Character Encoding Configurations in <web.xml>
  <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd" metadata-complete="false" version="5.0"> <jsp-config> <jsp-property-group> <url-pattern>*.jsp</url-pattern> <page-encoding>UTF-8</page-encoding> <default-content-type>text/html; UTF-8</default-content-type> </jsp-property-group> </jsp-config> </web-app>
- The <response-encoding> is configuration for HTTP response and is clearly separate from the JSP page character encoding configuration. But, it is very rare for a developer to create a JSP file with a full understanding of all this. Thus, <response-encoding><forced> has precedence over the JSP page character encoding and Response character encoding.

6.6. JSP Engines

Since web engines contain JSP engines, JSPs must be configured by each web engine or each application. For more information, refer to JSP Engine.

6.7. Response Headers

A user-custom HTTP response header can be defined by using name-value pairs.

The following example shows how to set the default user-custom header to include in a response using domain.xml.

<web-engine>
    ...
    <response-header>
        <custom-header>
            <header-field>
                <field-name>HeaderName1</field-name>
                <field-value>HeaderValue1</field-value>
            </header-field>
        </custom-header>
    </response-header>
    ...
</web-engine>

Item	Description
Custom Header	Defines the custom field that will be added to HTTP responses. Header Field: Specify the user-custom header. When setting multiple response headers, associate the name and value of each header with '=', and separate each header by a new line.

Item

Description

Custom Header

Defines the custom field that will be added to HTTP responses.

Header Field: Specify the user-custom header. When setting multiple response headers, associate the name and value of each header with '=', and separate each header by a new line.

If set successfully, a result message "Saved" is displayed. Since the response header setting cannot be applied dynamically, you need to restart the server to apply the setting.

6.8. Cookie Policy

A policy can be configured for reading a cookie from an HTTP request header or sending a cookie that was created by the application as an HTTP response. The cookie policy can be configured in domain.xml or in jeus-web-dd.xml by each application.

The following example shows how to set the cookie policy in domain.xml. This example sets the cookie encoding to UTF-8 as the cookie policy.

<web-engine>
    <cookie-policy>
        <write-value-on-header-policy>
            <apply-url-encoding-rule>true</apply-url-encoding-rule>
            <charset-encoding>UTF-8</charset-encoding>
        </write-value-on-header-policy>
    </cookie-policy>
</web-engine>

Item	Description
Apply Url Encoding Rule	Option to apply the URL encoding rule.
Charset Encoding	Charset encoding that is used when cookies are used for a response or interpretation regardless of whether the URL encoding rule will be applied. If not set, the request encoding will be used.

Item

Description

Apply Url Encoding Rule

Option to apply the URL encoding rule.

Charset Encoding

Charset encoding that is used when cookies are used for a response or interpretation regardless of whether the URL encoding rule will be applied. If not set, the request encoding will be used.

Since the cookie policy setting cannot be applied dynamically, you need to restart the server to apply the setting.

6.9. Sessions

The web engine session settings configure items such as session object sharing, session cookie configurations, and timeouts that are required to manage sessions.

Web engine level

You can configure sessions using the console tool. For more information about session configuration, refer to Session Configuration in JEUS Session Management Guide.
Context level

Sessions are configured in the <jeus-web-dd> element of jeus-web-dd.xml.

If sessions are configured at the web engine level, the configurations are shared within the web engine even if they are not configured at the context level. If sessions are configured both at the web engine level and the context level, the context level configurations have a higher precedence. The precedence of the configuration values is context level > web engine level. If an item is not configured at the context level, the web engine configuration will be used. If neither level contains the configuration, the default value of the web engine will be used.

For more information about sessions in a clustered environment, refer to Session Tracking in JEUS Session Management Guide.

6.10. Logs

This section describes how to configure logs.

Configuring Server Logs
Configuring Access Logs
Configuring Access Logs by Virtual Host
Formatting Access Logs
Filtering Access Logs by Writing the Code
Configuring User Logs

Configuring Server Logs

For more information about server logs, refer to Logging in JEUS Server Guide.

Configuring Access Logs

Web engine access logs can be configured through the console. Access logs are written to a file by default.

From JEUS 6 Fix #8 onwards, the access logs are set to use log rotation by default.

Log rotation saves the log file with a new name when the file exceeds a specified size or at a specified time, and records new logs in the existing file.

The following shows how to configure access logs in domain.xml.

XML Configuration for Access Logs: <domain.xml>

<domain xmlns="...">
    ...
    <servers>
        <server>
            <web-engine>
                <access-log>
                    <level>INFO</level>
                    <use-parent-handlers>false</use-parent-handlers>
                    <formatter-pattern>[%d{yyyy.MM.dd HH:mm:ss}][%l] [%J-%T] [%M-%N] %m</formatter-pattern>
                    <handler>
                        <file-handler>
                            <name>accessLogFileHandler</name>
                            <level>FINEST</level>
                            <enable-rotation>true</enable-rotation>
                            <valid-day>1</valid-day>
                            <buffer-size>1024</buffer-size>
                            <append>true</append>
                        </file-handler>
                    </handler>
                    <enable>true</enable>
                    <format>default</format>
                    <enable-host-name-lookup>false</enable-host-name-lookup>
                </access-log>
            </web-engine>
        <server>
    </servers>
    ...
</domain>

The default settings can be used without any specific configurations. Custom configurations may be necessary, especially when you need to change the access log format or exclude specific file extensions from the log. To use additional handlers other than the default handlers, add them in the <handler>. For more information about handlers, refer to Logging in JEUS Server Guide.

The following example changes the access log format from the default format to a user custom format.

<access-log>
    <level>INFO</level>
    <use-parent-handlers>false</use-parent-handlers>
    <formatter-pattern>[%d{yyyy.MM.dd HH:mm:ss}][%l] [%J-%T] [%M-%N] %m</formatter-pattern>
    ...
    <exclude-ext>ipg,txt</exclued-ext>
    <enable-host-name-lookup>false</enable-host-name-lookup>
</access-log>

The following describes each item of Advanced options.

Item	Description
Enable Host Name Lookup	Option to log the host name instead of the IP address when the %h format is used. Note that setting this option to true may cause overhead due to DNS lookup.
Exclude Ext	File extensions to be excluded from access logs. Multiple values can be specified with comma separators.
Filter Class	Filter class of the logger.
Use Parent Handlers	Option to use parent logger handlers. The default value is true, which prints log messages by using parent logger handlers.

Item

Description

Enable Host Name Lookup

Option to log the host name instead of the IP address when the %h format is used. Note that setting this option to true may cause overhead due to DNS lookup.

Exclude Ext

File extensions to be excluded from access logs. Multiple values can be specified with comma separators.

Filter Class

Filter class of the logger.

Use Parent Handlers

Option to use parent logger handlers. The default value is true, which prints log messages by using parent logger handlers.

In web engine access log configurations, the filter class and formatter pattern settings cannot be applied dynamically. Therefore, you need to restart the server to apply the setting.

Configuring Access Logs by Virtual Host

To create access logs by virtual host, the access logs must be configured in each virtual host. For more information, refer to Configuring Virtual Hosts.

Formatting Access Logs

The access log format can be configured in domain.xml.

<access-log>
    <level>INFO</level>
    <use-parent-handlers>false</use-parent-handlers>
    <formatter-pattern>[%d{yyyy.MM.dd HH:mm:ss}][%l] [%J-%T] [%M-%N] %m</formatter-pattern>
    ...
</access-log>

The formats primarily use '%' to express data, but other character strings can also be utilized.

JEUS 9 complies with Common Log Format (CLF). For more information about CLF, refer to http://httpd.apache.org/docs/2.4/logs.html.
For more information about changing the format using the console tool, refer to modify-web-engine-configuration in JEUS Reference Guide.

Web engines provide the following format aliases.

default

Default format provided by JEUS. This format adds the processing time (%D) to the common format that is the most commonly used in CLF. Due to performance reasons, "%l", which always generates "-", and " %l", which reads values from sessions, have been deleted.
```
%h %t \"%r\" %s %b %z %D
```
common

Most commonly used format in CLF. It is an alias for the following format.
```
%h %l %u %t \"%r\" %s %b
```
combined

Prints the Referrer and User-agent from the HTTP header. It is an alias for the following format.
```
%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"
```
debug

Adds the session ID (%S) and response processing thread name (%I) to the default format.
```
%h %t \"%r\" %s %b %z %D %u %S \"%I\"
```

The format can be set with an alias from the previous list.

default %S

In this case, the common alias is replaced by the following format and is registered to the web engine.

%h %l %u %t \"%r\" %s %b %z %D %S

Format setting can be modified and applied while a service is running. Hence, if the currently running service has a problem, set the debug format to record the session ID and response processing thread name.

Filtering Access Logs by Writing the Code

Access log filtering is provided to record only logs that meet specific conditions. Requests can be filtered by file extension using <exclude-ext>.

Starting from JEUS 7, the package has been changed from jeus.servlet.util to jeus.servlet.logger.

JEUS provides the jeus.servlet.logger.AccessLoggerFilter interface and jeus.servlet.logger.AbstractAccessLoggerFilter abstract class.

Definition of jeus.servlet.logger.AccessLoggerFilter Interface <AccessLoggerFilter.java>

package jeus.servlet.logger;

import java.util.logging.Filter;
import java.util.logging.LogRecord;

/**
 * This interface provides the information required to filter access logger.
 * This interface inherits {@link Filter}. It can define various filtering policies in
 * {@link Filter#isLoggable(java.util.logging.LogRecord)} using additionally provided interfaces.
 */
public interface AccessLoggerFilter extends Filter {
    /**
     * Returns the address of the remote client that accesses the server.
     *
     * @param record a LogRecord
     * @return remote client의 address. Returns null if the address is invalid.
     */
    public String getRemoteAddr( LogRecord record );

    /**
     * Returns the HTTP method of the request, e.g., GET, POST, PUT, etc.
     *
     * @param record a LogRecord
     * @return request method. Returns null if the return value is invalid.
     */
    public String getMethod( LogRecord record );

    /**
     * Returns the URI of the request.
     *
     * @param record a LogRecord
     * @return request uri. Returns null if the return value is invalid.
     */
    public String getRequestURI( LogRecord record );

    /**
     * Returns the response status, e.g., 200, 404
     *
     * @param record a LogRecord
     * @return status.
     */
    public int getStatus( LogRecord record );

    /**
     * Returns the processing duration in milliseconds.
     *
     * @param record a LogRecord
     * @return processing time. Returns -1 if the return value is invalid.
     */
    public long getProcessingTimeMillis( LogRecord record );
}

To use filters for certain patterns in the access log, the AccessLoggerFilter interface and AbstractAccessLoggerFilter abstract class can be used to easily implement and apply the filters.

User-created filter classes inherit jeus.servlet.logger.AbstractAccessLoggerFilter interface and must implement the isLoggable() method of the java.util.logging.Filter interface. When implementing the isLoggable() method, use the methods from the jeus.servlet.logger.AccessLoggerFilter API that are needed by the user.

The following example defines a filter class that disables leaving access logs if the request extension is '.gif'.

Example of Defining a Filter Class : <SimpleAccessLoggerFilter>

package sample;

import jeus.servlet.logger.AbstractAccessLoggerFilter;
import java.util.logging.*;

public class SimpleAccessLoggerFilter extends AbstractAccessLoggerFilter {
    public boolean isLoggable(LogRecord record) {
        String requestURI = getRequestURI(record);
        return requestURI != null && !requestURI.endsWith(".gif");
    }
}

The sample.SimpleAccessLoggerFilter is a user-defined class that extends the jeus.servlet.logger.AbstractAccessLoggerFilter class.
It implements the java.util.logging.Filter#isLoggable() method, and uses the jeus.servlet.util.AccessLoggerFilter#getRequestURI() method to get the client request URI.

Once the class is defined, compile the class. Add the file to the 'JEUS_HOME/domains/DOMAIN_HOME/lib/application' directory as a JAR file, and configure the filter for the web engine access log. For more information about configuring access logs, refer to Configuring Access Logs.

Configuring User Logs

By default, logs are stored in the server log file (JeusServer.log). ). To use a separate log file, configure a user log. For more information about the default user log file and its location, refer to Directory Structure.

Like server logs, user logs can be registered at the JEUS server level as well as in jeus-web-dd.xml for web applications. User logs can be created by each web application or in a specific log file.

The following explains how to configure user logs using domain.xml.

Configure it in the child tags of <user-logging>.

To create logs only for a web application named webapp, set '<name>' as in the following example. If 'jeus.systemuser' is entered without the name webapp, the user logs are configured for all web applications. For more information about each item in the Advanced Options section, refer to Configuring Access Logs. Other items, such as '<level>', can be optionally set as needed.

You can add handlers in <handler>. Enter the tag of the handler to be added as the user log handler. For more information about configuring each handler, refer to Logging in JEUS Server Guide. In this example, the <file-handler> tag is added to add a file handler.

<server>
    ...
    <user-logging>
        <name>jeus.systemuser.webuser.app1</name>
        <level>INFO</level>
        <use-parent-handlers>true</use-parent-handlers>
        <filter-class>...</filter-class>
        <formatter-pattern></formatter-pattern>
        <handler>
            <file-handler>
                <name>fileHandler</name>
                <level>FINEST</level>
            </file-handler>
        </handler>
    </user-logging>
    ...
</server>

6.11. Async Servlet Timeout Processing

As of Servlet 3.0, the number of threads that is required to process an async servlet timeout must be configured.

The following shows how to set the async servlet timeout processing using domain.xml.

<web-engine>
    <async-timeout-min-threads>10</async-timeout-min-threads>
</web-engine>

Since the async servlet timeout processing setting cannot be applied dynamically, you need to restart the server to apply the setting.

6.12. Web Engine Level Properties

You can set properties defined in JEUS using domain.xml. For more information about web engine properties, refer to Web Engine Properties in JEUS Reference Guide.

The following shows how to set properties using domain.xml.

Set the '<properties>' tag. Enter the property name as <key> and the value as <value>.

<web-engine>
    <properties>
        <property>
            <key>jeus.servlet.request.enableDns=false</key>
            <value>false</value>
        </property>
    </properties>
</web-engine>

It is recommended to configure properties through the '<properties>' tag. You can also configure properties using the '<jvm-option>' tag in domain.xml.

6.13. Preventing Web Attacks

Malicious users can attack JEUS by sending a large volume of requests with a large amount of data. When this happens, normal requests can be delayed or fail to receive a response.

To prevent these kinds of attacks, the JEUS administrator can set conditions to determine which requests are malicious and deny them. By default, this is configured in the web engine of the server but can also be set for each listener or connector that receives the request from the web engine. They can be configured in the HTTP listener, WebtoB connector, and AJP13. For more information about configuring each listener or connector, refer to Common Listener Settings.

Properly configure the following items to prevent web attacks.

The following shows how to set the web attack prevention using domain.xml.

<domain xmlns="..." version="...">
    <servers>
        <server>
            <web-engine>
                <web-connections>
                    <http-listener>
                        <name>SERVER-HTTP</name>
                        <thread-pool>
                            <min>10</min>
                            <max>20</max>
                            <max-idle-time>300000</max-idle-time>
                            <max-queue>-1</max-queue>
                        </thread-pool>
                        <postdata-read-timeout>600000</postdata-read-timeout>
                        <max-post-size>-1</max-post-size>
                        <max-parameter-count>-1</max-parameter-count>
                        <max-header-count>-1</max-header-count>
                        <max-header-size>8192</max-header-size>
                        <max-querystring-size>8192</max-querystring-size>
                        <server-access-control>false</server-access-control>
                        <allowed-server>...</allowed-server>
                        <server-listener-ref>http-server</server-listener-ref>
                    </http-listener>
                </web-connections>
            <web-engine>
        <server>
    </servers>
</domain>

Configure each item in domain.xml. Each listener can use these settings to prevent web attacks. For more information about each configuration item, refer to Common Listener Settings.

6.14. Blocking HTTP Requests with a Specific URL Pattern

For an example of blocking HTTP requests with a specific URL pattern, let’s assume that the HTTP client sent the following request.

GET /examples/%2e%2e%2fdb.txt HTTP/1.1

The web container must decode the URL in the request URI first.

/examples/../db.txt

By doing this, the user can access files that are not related to the actual HTTP service. Typically, clients with a malicious intent send the request URI in this way.

Since the web container cannot detect all requests with a malicious intent, the user must directly provide settings to prevent malicious patterns. The settings are applied only to HTTP requests and if any match is found within the URI except for the query string, the request is handled as a '404 Not Found' unconditionally.

This setting was configured in the property file from JEUS 6 to JEUS 7 Fix#1, but starting from JEUS 7 Fix#2, it is configured in domain.xml.

The following shows configuration through domain.xml.

Configure the child tags of <blocked-url-patterns>.

<web-engine>
    ...
    <blocked-url-patterns>
        <encoded-pattern>%00</encoded-pattern>
        <decoded-pattern>#</decoded-pattern>
        <deny-last-space-character>true</deny-last-space-character>
        <deny-null-character>true</deny-null-character>
    </blocked-url-patterns>
    ...
</web-engine>

'Encoded Pattern' is used to check if the URI sent from the HTTP client contains the specified strings. The URI from the client is used after it is URL decoded by the web container. Here, it is checked whether the value specified in 'Decoded Pattern' is included in the URL. If any 'Encoded Pattern' is set, the basic pattern will not be processed. (Same for 'Decoded Pattern')

If no configuration exists, the web container processes %2e, %2f, %5c, %23, and %00 as 404 in case of an Encoded Pattern and # and \ as 404 in case of a Decoded Pattern.

Patterns are not case-sensitive. They are always converted to lower case letters before being processed.

7. Tuning the Web Engine

Consider the following items for the best web engine performance.

Set <output-buffer-size> to an appropriate size. If using with WebtoB, set appropriate values for <send-buffer-size> and <receive-buffer-size> inside <webtob-connector><webtob-connector>.
Set <check-included-jspfile> to 'false' unless the included JSPs have been modified. If it is set to false, the included JSP files will not be checked for modification to improves performance.
If the JSP files have not been modified, the jeus.servlet.jsp.reload property is set to false. This prevents querying the metadata from the file system on every JSP call.