Web applications consist of static and dynamic contents that are required to run web-based services requested by clients.

Before being deployed to web engines, a web context must be packaged into a JAR file, a compressed file with the extension '.war'. The packaged file is called a WAR (Web ARchive) file. The following is the structure of a WAR file.

[Figure 3.1] WAR File Structure

The web.xml and jeus-web-dd.xml files should only be created under the 'WEB-INF/' directory if necessary.

The following is an example of jeus-web-dd.xml. Refer to "13. jeus-web-dd.xml configuration" of "JEUS XML Reference" for information about items that have been omitted.

<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="7.0">
    <context-path>/examples</context-path>
    <enable-jsp>true</enable-jsp>
    <auto-reload>
        <enable-reload>true</enable-reload>
        <check-on-demand>true</check-on-demand>
    </auto-reload>
    <added-classpath>
        <class-path>/home/user1/libs/lib.jar</class-path>
    </added-classpath>
    <session-config>
        . . .
    </session-config>
    <async-config>
        <async-timeout-millis>600000</async-timeout-millis>
        <background-thread-pool>
            <min>0</min>
            <max>10</max>
        </background-thread-pool>
        <dispatch-thread-pool>
            <min>0</min>
            <max>10</max>
        </dispatch-thread-pool>
    </async-config>
    <properties>
        <property>
            <key>jeus.servlet.jsp.modern</key>
            <value>true</value>
        </property>
    </properties>
</jeus-web-dd>

The following table describes the configuration tags.

<webinf-first>
    <enabled>true</enabled>
    <excluded-package>package.name.</excluded-package>
    ...
</webinf-first>

This guide does not cover web context redeployment.

For more information, refer to ????.

Shared libraries can be added to the 'JEUS_HOME/lib/shared' directory instead of the 'WEB-INF/lib' directory so that they can be shared by multiple applications. When modifying the libraries.xml file and redeploying the module, the updated libraries will be applied without restarting JEUS.

To add a shared library, add the <library> tag and configure the JAR files to share in the 'JEUS_HOME\lib\shared\libraries.xml' file as in the following example.

The specification version and the implementation class version can each be configured.

<libraries xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <!-- DO NOT MODIFY JSF1.2 and JSTL1.2 libraries!!! -->
    <library>
        <library-name>jsf</library-name>
        <specification-version>1.2</specification-version>
        <implementation-version>1.2_06</implementation-version>
        <files dir=".">
            <include name="jsf-injection-provider.jar"/>
        </files>
        <files dir="jsf_ri_1.2"/>
    </library>    
    <library>
        <library-name>jsf</library-name>
        <specification-version>2.0</specification-version>
        <implementation-version>2.0.0</implementation-version>
        <files dir=".">
            <include name="jsf-injection-provider.jar"/>
            <include name="jsf-weld-integration.jar"/>
        </files>
        <files dir="jsf_ri_2.0"/>
    </library>
    <library>
        <library-name>jstl</library-name>
        <specification-version>1.2</specification-version>
        <implementation-version>1.2</implementation-version>
        <files dir="jstl_1.2"/>
    </library>

    <!-- Add user libraries from here -->
    <library>
        <library-name>myLibrary</library-name>
        <specification-version>2.0</specification-version>
        <implementation-version>2.1</implementation-version>
        <files dir=".">
            <include name="commons-logging.jar"/>
            <include name="commons-util.jar"/>
        </files>
        <files dir="myLib-2.1"/>
    </library>
</libraries>

To reference the configured shared libraries, set <library-ref> in jeus-web-dd.xml as in the following. If the version is not specified, the highest version of the library that is registered in libraries.xml will be referenced.

   <library-ref>
       <library-name>myLibrary</library-name>
       <specification-version>2.0</specification-version>
   </library-ref>

Configuring JSF and JSTL Libraries

In the libraries.xml file described in [Example 3.2], JSF and JSTL are added as shared libraries. Since the Java EE standard includes JSF and JSTL, they are provided in JEUS by default.

The libraries can be provided by JEUS, but this will only allow one each of JSF and JSTL implementation class to be used. Since JSF implementation class has multiple versions besides 2.0, including 1.2, Apache myfaces, and SUN RI, JEUS provides the JSF and JSTL as shared libraries so that multiple implementations can be used.

The implementation classes are classified by their locations and types as in the following.

[Warning]

The following describes the changes have been made starting from JEUS 7 Fix #2.

Starting from this version, the Oracle JSF RI is not automatically added to the 'JEUS_HOME/lib/shared' directory. To use it, explicitly configure the <library-ref> setting in jeus-web-dd.xml.

Use the following declaration to use the libraries included in the 'JEUS_HOME/lib/shared' directory.

<library-ref>
    <library-name>jsf</library-name>
</library-ref>

Also, JEUS has been modified to not automatically add the web listener included in Oracle JSF RI 2.x. It must be configured in the <listener> setting of web.xml.

<listener>
    <listener-class>com.sun.faces.config.ConfigureListener</listener-class>
</listener>

To share the same JSF or JSTL libraries in multiple applications, manually configure the <library> setting in 'JEUS_HOME/lib/shared/libraries.xml' and that <library-ref> setting in jeus-web-dd.xml.

For JSF, the resources provided by WAS must be accessible from managed beans by using annotations such as @EJB and @Resource and WAS must be able to inject the resources that are specified by the annotations.

JEUS provides 'jsf-injection-provider.jar' as a shared library to support the injection of JEUS to JSF RI. The shared library exists in the following directory.

JEUS_HOME/lib/shared

The library is automatically included if web.xml contains the javax.faces.webapp.FacesServlet class.

A web context can be configured to resolve compatibility issues with previous versions JEUS or another WAS.

Compatibility with Previous Versions of JEUS

Prior to Servlet 2.4, many standards were not described properly. They were supplemented over the course of servlet 2.4 and 2.5 releases and this naturally resulted in restrictions being created in JEUS. To resolve these issues, JEUS started supporting non-standard operations. Due to such reasons, JEUS 4 web applications may not be compatible with JEUS 6.

JEUS must comply with servlet and JSP standards, and also ensure compatibility with the existing applications, but these requirements can cause conflicts. Usually when the javax.servlet standard API or internal operation is modified to comply with the standard, problems may arise if there are applications that were created based on the previous faulty operation. In this situation, the applications must be modified since compliance requirements have a higher precedence. Otherwise, the applications cannot run in other containers, and they may conflict with frameworks that comply with the servlet standards when the applications are upgraded.

If such issues are not identified in advance until the official start of the services, this may require the modification of JEUS operations instead of user applications. To resolve this, JEUS provides properties that can be configured for compatibility with previous versions.

For more information about compatibility of JSP engines and JEUS properties, refer to "4.4.3. Web Context Options for JSP Backward Compatibility" and JEUS Reference Book. "1.6.3.3. Properties for Compatibility".

Compatibility with Other WASs

Before Servlet 2.4, web applications were developed using servlets and JSPs directly, but a web framework is now being used. Starting from Java EE 5, JSF and JSTL libraries have been added to the standard web frameworks. Most web frameworks use Tomcat, a reference implementation class for servlet and JSP specifications, for development and testing. This may cause compatibility issues if the web frameworks support non-standard functions.

Compatibility can be configured selectively in jeus-web-dd.xml when there is a compatibility problem. For more information about configuring jeus-web-dd.xml, refer to JEUS Reference Book. "1.6. Web Engine Properties".

Separate configurations are required to use the following additional functions provided by JEUS.

The servlet standard specifies that the default servlet, which is provided by WAS, is used for a request that is neither a servlet nor JSP. The default servlet is called a ResourceServlet.

Map jeus.servlet.servlets.ResourceServlet to the <servlet-mapping> setting in web.xml as in the following.

<servlet-mapping>
    <servlet-name>jeus.servlet.servlets.ResourceServlet</servlet-name>
    <url-pattern>/static/*</url-pattern>
</servlet-mapping> 

Registering mvc:default-servlet-handler in Spring 3.0 or Later

From JEUS 8, the mvc:default-servlet-handler does not need to be registered in Spring 3.0 or later. Like Tomcat, JEUS default servlet is provided in the name of "default".

In JEUS v7.0 Fix #1, register it in web.xml as in the folllowing.

Since Spring calls ServletContext.getNamedDispatcher() with the name "default", JEUS ResourceServlet is used.

Registering ProgressListener when Servlet 3.0 Multipart Function is Used

Starting from Servlet 3.0, the multipart-config can be configured per servlet to assign the web container to process multipart/form-data of the POST request. A progressListener must be registered to trigger an event about the processing progress.

This section describes configuring web security for each application in jeus-web-dd.xml.

Redirect Location Security Configurations

Applications can send the 302 Found response message by using the standard API javax.servlet.http.HttpServletResponse.sendRedirect(String location). In this case, the location parameter value will be converted to URL and set to the location header without checking the value. This allows users with malicious intent to use attacks like CRLF injection. To prevent this, applications can implement the jeus.servlet.security.RedirectStrategy interface and configure it in jeus-web-dd.xml.

The following is an example of configuring the jeus.servlet.security.RedirectStrategy interface.

package jeus.servlet.security;

import javax.servlet.http.HttpServletRequest;

public interface RedirectStrategy {
    /**
     * Makes the redirect URL.
     *
     * @param location the target URL to redirect to, for example "/login"
     */
    String makeRedirectURL(HttpServletRequest request, String location)
        throws IllegalArgumentException;
}         

This interface can be implemented as in the following.

package jeus.servlet.security;
import javax.servlet.http.HttpServletRequest;

public class RejectCrlfRedirectStrategy implements RedirectStrategy {
    private Pattern CR_OR_LF = Pattern.compile("\\r|\\n");

    @Override
    String String makeRedirectURL(HttpServletRequest request, String location)
       throws IllegalArgumentException {
        if (CR_OR_LF.matcher(location).find()) {
           throw new IllegalArgumentException("invalid characters (CR/LF) in redirect location");
        }
       return makeAbsolute(location);
    }

    private String makeAbsolute(String location) {
       // make code for make absolute path
    }
}         

Jeus-web-dd.xml can be configured as in the following.

...
<web-security>
    <redirect-strategy-ref>
    jeus.servlet.security.RejectCrlfRedirectStrategy
    </redirect-strategy-ref>
</web-security>
..

The <redirect-strategy-ref> setting is set to an implementation class of the jeus.servlet.security.RedirectStrategy interface. This class must be included in the web application class path.

The jeus.servlet.security.RejectCrlfRedirectStrategy class is a default RedirectStrategy provided. If a location that contains CR, LF, or CRLF character is sent to the sendRedirect API, an HTTP 500 error will occur.

In addition, the jeus.servlet.security.RemoveCrlfRedirectStrategy method that replaces CR, LF, or CRLF with an empty string is provided.

This section describes how to apply the security roles that are defined in web.xml to system users and groups. This mapping is described in jeus-web-dd.xml.

The following is a sample web.xml file.

<web-app>
    <security-role>
        <role-name>manager</role-name>
    </security-role>
    <security-role>
        <role-name>developer</role-name>
    </security-role>
    <servlet>
        . . .
    </servlet>
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>
                MyResource
            </web-resource-name>
            <url-pattern>/jsp/*</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>manager</role-name>
        </auth-constraint>
    </security-constraint>
</web-app>

In the previous example, two security roles are declared in bold. The third bolded element shows how the manager role is used in the <security-constraint> tag.

The previous mapping can be defined in jeus-web-dd.xml as in the following.

<jeus-web-dd  xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="7.0"> 
     . . .
     <role-mapping>
         <role-permission>
             <principal>Peter</principal>
             <role>manager</role>
         </role-permission>
         <role-permission>
             <principal>Linda</principal>
             <role>developer</role>
         </role-permission>
     </role-mapping>
     . . .
</jeus-web-dd>

When applications are deployed in a production environment, the manager and developer roles must be bound to a special user in the system.

This mapping is defined in the <context><role-mapping> setting. The <role-mapping> tag contains the <role-permission> tag which can be used to define the <principal-to-role> mapping.

The following child tags are also bound.

In the previous example, two roles, "manager" and "developer", are mapped to "Peter" and "Linda", respectively.

Since the roles are mapped to the actual users, EJB references, resource references, and managed object references must also be mapped to the actual system resources.

The following is an example of symbolic reference mapping.

<web-app>
    . . .
    <ejb-ref>
        <ejb-ref-name>ejb/account</ejb-ref-name>
        <ejb-ref-type>Entity</ejb-ref-type>
        <home>com.mycompany.AccountHome</home>
        <remote>com.mycompany.Account</remote>
    </ejb-ref>
    <resource-ref>
        <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
        <res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>
    <resource-env-ref>
        <resource-env-ref-name>
            jms/StockQueue
        </resource-env-ref-name>
        <resource-env-ref-type>
            javax.jms.Queue
        </resource-env-ref-type>
    </resource-env-ref>
    . . .
</web-app>

To register the web application, all symbolic reference names used in the <ejb-ref>, <resource-ref>, <resource-env-ref> settings of web.xml must be mapped to the JNDI names of the corresponding resources. To map them, add the corresponding <ejb-ref>, <res-ref>, and <res-env-ref> tags in jeus-web-dd.xml.

The tags contain the following child tags.

The following example of jeus-web-dd.xml maps the JNDI names to the aforementioned three references.

<jeus-web-dd  xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="7.0">
    . . .
    <ejb-ref>
        <jndi-info>
            <ref-name>ejb/account</ref-name>
            <export-name>AccountEJB</export-name>
        </jndi-info>
    </ejb-ref>
    <res-ref>
        <jndi-info>
            <ref-name>jdbc/EmployeeAppDB</ref-name>
            <export-name>EmployeeDB</export-name>
        </jndi-info>
    </res-ref>
    <res-env-ref>
        <jndi-info>
            <ref-name>jms/StockQueue</ref-name>
            <export-name>StockQueue</export-name>
        </jndi-info>
    </res-env-ref>
    . . .
</jeus-web-dd>

If a deployed web context is changed or the context needs to be reset, the web context can be reloaded instead of being deleted and redeployed.

WebAdmin or the console tool can be used to reload web contexts.

Using WebAdmin

Web contexts can be reloaded in WebAdmin using the following steps.

Click [Applications] to go to the list of applications. In the list, click [reload] to view the result.

[Figure 3.5] Reloading Web Contexts

Using the Console Tool

The console tool can be used to reload web contexts.

Execute the reload-web-context command as in the following. For more information about the reload-web-context command, refer to JEUS Reference Book. "4.2.8.22. reload-web-context".

reload-web-context -ctx <context-name>
seccessfully reloaded

To use thread pools provided by JEUS when web contexts are processing asynchronous requests, the relevant information needs to be configured in the <async-config> element of jeus-web-dd.xml. After configuring the <async-config> element, asynchronous thread pool information can be monitored.

The following is an example of configuring jeus-web-dd.xml.

...
<async-config>
    <dispatch-thread-pool>
        <min>5</min>
        <max>20</max>
    </dispatch-thread-pool>
    <background-thread-pool>
        <min>5</min>
        <max>20</max>
    </background-thread-pool>
    <async-timeout-millis>120000</async-timeout-millis>
</async-config>
...

The following describes each configuration tag.

The async thread pool information can be checked in WebAdmin.

Using WebAdmin

The thread information of web contexts can be checked in WebAdmin using the following steps.

Administrators can suspend a deployed web context that is running, and resume it later. Refer to "3.5.4. Resuming Web Contexts" for detailed information about resuming web contexts.

Using WebAdmin

For information about suspending web contexts in WebAdmin refer to JEUS Applications & Deployment Guide. "4.3.7. Suspending Applications".

Using the Console Tool

The console tool can be used to suspend web contexts.

Execute the suspend-web-component command as in the following. For more information about the suspend-web-component command, refer to JEUS Reference Book. "4.2.8.35. suspend-web-component".

suspend-web-component -ctx <context>

Suspended web contexts can be resumed.

WebAdmin and the console tool can be used to resume suspended web contexts.

Using WebAdmin

For information about resuming suspended web contexts in WebAdmin, refer to JEUS Applications & Deployment Guide. "4.3.6. Starting Applications".

Using the Console Tool

The console tool can be used to resume suspended web contexts.

Execute the resume-web-component command as in the following. For more information about the resume-web-component command, refer to JEUS Reference Book. "4.2.8.31. resume-web-component".

resume-web-component -ctx <context>

Application developers must directly handle the threads due to the nature of asynchronous processing programming, and this may trigger the following errors.

Some of these errors cannot be detected during testing, but they may occur when too much load is incurred in the production environment. Note that the application developers, and not JEUS, are responsible for preventing these errors.

Creating Too Many Threads

Creating too many threads reduces the performance of the JVM or causes an OutOfMemoryError to occur. Following is an example of a faulty asynchronous processing programing that creates too many threads.

import javax.servlet.AsyncContext;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = "/WrongAsyncServlet1", asyncSupported = true)
public class WrongAsyncServlet1 extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        AsyncContext asyncContext = req.startAsync();
        Thread thread = new Thread(new TestRunnable(asyncContext));
        thread.start();
    }

    private class TestRunnable implements Runnable {
        private final AsyncContext asyncContext;

        public TestRunnable(AsyncContext asyncContext) {
            this.asyncContext = asyncContext;
        }

        @Override
        public void run() {
        }
    }
}

There can be more than thousands of concurrent asynchronous requests, which creates thousands of concurrent threads. This can greatly reduce the performance of the JVM or cause an "OutOfMemoryError: unable to create new native thread" to occur. Therefore, it is recommended to use the javax.servlet.AsyncContext#start(Runnable) method or a thread pool that can be directly managed.

AsyncContext asyncContext = req.startAsync();
asyncContext.start(new TestRunnable(asyncContext));

Sharing Unsafe Objects with Other Threads

Sharing unsafe objects that are not supposed to be shared with other threads can reduce the performance, result in a deadlock, or violate data integrity.

The following is an example of a faulty asynchronous program that allows different threads to share unsage objects.

import javax.servlet.AsyncContext;
import javax.servlet.ServletException;
import javax.servlet.ServletInputStream;
import javax.servlet.ServletOutputStream;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = "/WrongAsyncServlet2", asyncSupported = true)
public class WrongAsyncServlet2 extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)해
            throws ServletException, IOException {
        AsyncContext asyncContext = req.startAsync();
        asyncContext.start(new TestRunnable(asyncContext));밍

        byte[] buffer = new byte[1024];
        ServletInputStream inputStream = req.getInputStream();
        inputStream.read(buffer);

        ServletOutputStream outputStream = resp.getOutputStream();
        outputStream.write(buffer);
    }

    private class TestRunnable implements Runnable {
        private final AsyncContext asyncContext;

        public TestRunnable(AsyncContext asyncContext) {
            this.asyncContext = asyncContext;
        }

        @Override
        public void run() {
            byte[] buffer = new byte[1024];
            try {
                ServletInputStream inputStream =
                       asyncContext.getRequest().getInputStream();
                inputStream.read(buffer);
            } catch (IOException e) {
                //log error
                return;
            }

            ServletOutputStream outputStream;
            try {
                outputStream = asyncContext.getResponse().getOutputStream();
                outputStream.write(buffer);
            } catch (IOException e) {
                //log error
                return;
            }
        }
    }
}

The previous example shows multiple threads sharing the ServletInputStream, Reader object, the ServletOutputStream that can be obtained from the Response object, or the Writer object. According to the servlet standard, JEUS does not take responsibility for security of such operations. If asynchronous processing, which is started in the filter or the servlet, is transferred to another thread, if possible, the thread must handle the operation instead of the filter or the servlet codes. This can help prevent programming errors caused by incorrect multi-thread programming knowledge, including performance reduction, deadlocks, and data integrity violation.

Use the javax.servlet.ServletRequest#isAsyncStarted() method to check whether asynchronous processing was started from the servlet or the filter which does not directly call the startAsync() method.

Using javax.servlet.RequestDispatcher from Asynchronous Threads

Using the javax.servlet.RequestDispatcher class from asynchronous threads can cause the program not to work in the intended way or an exception to occur.

The following is an example of a faulty asynchronous processing program that uses the javax.servlet.RequestDispatcher class from an asynchronous thread.

import javax.servlet.AsyncContext;
import javax.servlet.RequestDispatcher;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = "/WrongAsyncServlet3", asyncSupported = true)
public class WrongAsyncServlet3 extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        AsyncContext asyncContext = req.startAsync();
        asyncContext.start(new TestRunnable(asyncContext));
    }

    private class TestRunnable implements Runnable {
        private final AsyncContext asyncContext;

        public TestRunnable(AsyncContext asyncContext) {
            this.asyncContext = asyncContext;
        }

        @Override
        public void run() {
            // ...... do something

            RequestDispatcher requestDispatcher =
                asyncContext.getRequest().getRequestDispatcher("/views/report.jsp");
            try {
                requestDispatcher.forward(asyncContext.getRequest(), 
                 asyncContext.getResponse());
            } catch (ServletException e) {
                // log error
            } catch (IOException e) {
                // log error
            }
        }
    }
}

The javax.servlet.AsyncContext class provides a way of dispatching from the asynchronous processing thread to another servlet or JSP.

asyncContext.dispatch("/views/report.jsp");

There are other precautions in addition to those for the servlet standard.