3. Configuration

3.1 Configuring the Embedded Tomcat Servlet Container

Gemini Web Container embeds an OSGi-enhanced version of the Tomcat Servlet Container in order to provide support for deploying Java EE WARs and OSGi Web Application Bundles. You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called tomcat-server.xml rather than server.xml. If you do not want to use the default settings, you can provide the tomcat-server.xml file located in the $GW_HOME/config directory.

Here's an extract of the default configuration distributed with the GW.

<?xml version='1.0' encoding='utf-8'?>
<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.core.JasperListener" />

  <Service name="Catalina">
    
    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" />

    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

    <Engine name="Catalina" defaultHost="localhost">

      <Host name="localhost" deployOnStartup="false" autoDeploy="false"
            unpackWARs="false" createDirs="false">

      </Host>
    </Engine>
  </Service>
</Server>

Description of the Default Apache Tomcat Configuration

The following bullets describe the main elements and attributes in the default tomcat-server.xml file; for details about updating this file to further configure the embedded Apache Tomcat server, see the Apache Tomcat Configuration Reference.

[Tip]Relative paths

If the configured path to a directory or file does not represent an absolute path, GW typically interprets it as a path relative to the $GW_HOME directory.

  • The root element of the tomcat-server.xml file is <Server>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The shutdown attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The port attribute specifies the TCP/IP port number that listens for a shutdown message.

  • The <Listener> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on.

  • The <Service> XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a <Service> element can have many <Connector> elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can define only a single <Engine> element for any given <Service> element.

    The sample tomcat-server.xml file above includes two <Connector> elements: one for the HTTP transport, and one for the AJP transport. The file also includes a single <Engine> element, as required.

  • The first connector listens for HTTP requests at the 8080 TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port 8443.

  • The second AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.

  • The engine has a logical name of Catalina; this is the name used in all log and error messages so you can easily identify problems. The value of the defaultHost attribute refers to the name of a <Host> child element of <Engine>; this host processes requests directed to host names on this servlet container.

  • The <Host> child element represents a virtual host, which is an association of a network name for a server (such as www.mycompany.com) with the particular server on which Catalina is running.

Connector Configuration

The Gemini Web Container supports the configuration of any connector supported by Apache Tomcat. See the default configuration above for syntax examples, and for further details of the configuration properties supported for various <Connector> implementations, consult the official Tomcat HTTP Connector documentation. For detailed instructions on how to configure Tomcat's SSL support, consult the official Tomcat SSL Configuration HOW-TO.

Cluster Configuration

Gemini Web Container supports standard Apache Tomcat cluster configuration. By default, clustering of the embedded servlet container is disabled, and the default configuration does not include any clustering information. See Tomcat Clustering/Session Replication HOW-TO for detailed information about enabling and configuring clustering.

Default web.xml Configuration

Java Servlet specification enables web applications to provide deployment descriptor (web.xml) in the WEB-INF directory. Apache Tomcat introduces a default web.xml which is similar to web application's web.xml, but provides configurations that are applied to all web applications. When deploying a web application, Apache Tomcat uses the default web.xml file as a base configuration. If the web application provides its own configurations via web.xml (the one located in the web application's WEB-INF) or annotations, they overwrite the default ones. In Gemini Web Container you can also provide default configurations for all web applications. If you want to change/extend the default configurations, you can provide the default web.xml file located in the $GW_HOME/config directory.

[Tip]Tip
Be careful when changing/extending the default web.xml as this will affect all web applications.

Here's an extract of the default configuration distributed with the GW.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    <servlet>
        <servlet-name>default</servlet-name>
        <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>listings</param-name>
            <param-value>false</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>jsp</servlet-name>
        <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
        <init-param>
            <param-name>fork</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
            <param-name>xpoweredBy</param-name>
            <param-value>false</param-value>
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>jsp</servlet-name>
        <url-pattern>*.jsp</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>jsp</servlet-name>
        <url-pattern>*.jspx</url-pattern>
    </servlet-mapping>

    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>

    <mime-mapping>
        <extension>abs</extension>
        <mime-type>audio/x-mpeg</mime-type>
    </mime-mapping>
    ......
    <mime-mapping>
        <extension>ppt</extension>
        <mime-type>application/vnd.ms-powerpoint</mime-type>
    </mime-mapping>

    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
        <welcome-file>index.htm</welcome-file>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

</web-app>

The following bullets describe the main elements in the default web.xml file.

  • The <Servlet> XML element declares a given servlet and its configurations. The sample web.xml file above includes two <Servlet> elements.

    • The default servlet serves static resources and processes the requests that are not mapped to any servlet. For details about default servlet configuration, see the Apache Tomcat Default Servlet Reference..

    • The jsp servlet serves the requests to JavaServer Pages. It is mapped to the URL pattern "*.jsp" and "*.jspx". For details about jsp servlet configuration, see the Apache Tomcat Jasper 2 JSP Engine..

  • The <servlet-mapping> XML element specifies the mapping between the servlet and URL pattern.

  • The <session-config> XML element defines the session configuration for one web application. The sample web.xml file above specifies that the session timeout for all web applications will be 30 minutes by default.

  • The <mime-mapping> XML element defines a mapping between a filename extension and a mime type. When serving static resources, a "Content-Type" header will be generated based on these mappings.

  • The <welcome-file-list> XML element specifies a list of welcome files. When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory. If the "welcome file" exists it will be served, otherwise 404 status or directory listing will be returned, depending on the default servlet configuration.

Context Configuration

Gemini Web Container supports standard Apache Tomcat web application context configuration. The Apache Tomcat Configuration Reference has a section on The Context Container which describes the mechanism that is used in GW for searching context configuration files and details the context configuration properties.

Context configuration files may be placed in the following locations, where [enginename] is the name of Tomcat's engine ('Catalina' by default) and [hostname] names a virtual host ('localhost' by default), both of which are configured in tomcat-server.xml:

  • $GW_HOME/config/context.xml provides the default context configuration file for all web applications.

  • The $GW_HOME/config/[enginename]/[hostname] directory may contain:

    • The default context configuration for all web applications of a given virtual host in the file context.xml.default.

    • Individual web applications' context configuration files as described in the Apache Tomcat Configuration Reference. For example, the context for a web application with context path foo may be configured in foo.xml.

Note that the following context configuration features are not supported in Gemini Web Container:

  • Custom class loaders.

  • Specifying the context path. This is specified using the Web-ContextPath header in the web application's MANIFEST.MF file.

  • Specifying the document base directory.