| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>3. Configuration</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Gemini Web User Guide"><link rel="up" href="index.html" title="Gemini Web User Guide"><link rel="prev" href="ch02s02.html" title="2.2 Installing from the ZIP Download"><link rel="next" href="ch03s02.html" title="3.2 Configuring the OSGi Framework"><!--Begin Google Analytics code--><script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script><script type="text/javascript"> |
| var pageTracker = _gat._getTracker("UA-2728886-3"); |
| pageTracker._setDomainName("none"); |
| pageTracker._setAllowLinker(true); |
| pageTracker._trackPageview(); |
| </script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. Configuration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s02.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch03s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="configuring"></a>3. Configuration</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-tomcat"></a>3.1 Configuring the Embedded Tomcat Servlet Container</h2></div></div></div><p> |
| Gemini Web Container |
| embeds an OSGi-enhanced version of the <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat Servlet Container</a> |
| in order to provide support for deploying Java EE WARs and OSGi <span class="emphasis"><em>Web Application Bundles</em></span>. |
| You configure the embedded Servlet container using the standard Apache Tomcat configuration. |
| The main difference is that the configuration file is called <code class="filename">tomcat-server.xml</code> rather than <code class="literal">server.xml</code>. |
| If you do not want to use the default settings, you can provide the <code class="literal">tomcat-server.xml</code> file located in the <code class="literal">$GW_HOME/config</code> directory. |
| </p><p>Here's an extract of the default configuration distributed with the GW.</p><pre class="programlisting"><<span class="hl-tag">?xml version='1.0' encoding='utf-8'?</span>> |
| <<span class="hl-tag">Server</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8005"</span> <span class="hl-attribute">shutdown</span>=<span class="hl-value">"SHUTDOWN"</span>> |
| <<span class="hl-tag">Listener</span> <span class="hl-attribute">className</span>=<span class="hl-value">"org.apache.catalina.core.JasperListener"</span> /> |
| |
| <<span class="hl-tag">Service</span> <span class="hl-attribute">name</span>=<span class="hl-value">"Catalina"</span>> |
| |
| <<span class="hl-tag">Connector</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8080"</span> <span class="hl-attribute">protocol</span>=<span class="hl-value">"HTTP/1.1"</span> |
| <span class="hl-attribute">connectionTimeout</span>=<span class="hl-value">"20000"</span> |
| <span class="hl-attribute">redirectPort</span>=<span class="hl-value">"8443"</span> /> |
| |
| <<span class="hl-tag">Connector</span> <span class="hl-attribute">port</span>=<span class="hl-value">"8009"</span> <span class="hl-attribute">protocol</span>=<span class="hl-value">"AJP/1.3"</span> <span class="hl-attribute">redirectPort</span>=<span class="hl-value">"8443"</span> /> |
| |
| <<span class="hl-tag">Engine</span> <span class="hl-attribute">name</span>=<span class="hl-value">"Catalina"</span> <span class="hl-attribute">defaultHost</span>=<span class="hl-value">"localhost"</span>> |
| |
| <<span class="hl-tag">Host</span> <span class="hl-attribute">name</span>=<span class="hl-value">"localhost"</span> <span class="hl-attribute">deployOnStartup</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">autoDeploy</span>=<span class="hl-value">"false"</span> |
| <span class="hl-attribute">unpackWARs</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">createDirs</span>=<span class="hl-value">"false"</span>> |
| |
| <<span class="hl-tag">/Host</span>> |
| <<span class="hl-tag">/Engine</span>> |
| <<span class="hl-tag">/Service</span>> |
| <<span class="hl-tag">/Server</span>></pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="overview-tomcat-servlet-container"></a>Description of the Default Apache Tomcat Configuration</h3></div></div></div><p> |
| The following bullets describe the main elements and attributes in the default <code class="literal">tomcat-server.xml</code> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a>. |
| </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip: Relative paths"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left">Relative paths</th></tr><tr><td align="left" valign="top"><p>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 <code class="filename">$GW_HOME</code> directory.</p></td></tr></table></div><div class="itemizedlist"><ul type="disc"><li><p>The root element of the <code class="literal">tomcat-server.xml</code> file is <code class="literal"><Server></code>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The <code class="literal">shutdown</code> 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 <code class="literal">port</code> attribute specifies the TCP/IP port number that listens for a shutdown message.</p></li><li><p>The <code class="literal"><Listener></code> 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.</p></li><li><p>The <code class="literal"><Service></code> 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 <code class="literal"><Service></code> element can have many <code class="literal"><Connector></code> 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 <code class="literal"><Engine></code> element for any given <code class="literal"><Service></code> element.</p><p>The sample <code class="literal">tomcat-server.xml</code> file above includes two <code class="literal"><Connector></code> elements: one for the HTTP transport, and one for the AJP transport. The file also includes a single <code class="literal"><Engine></code> element, as required.</p></li><li><p>The first connector listens for HTTP requests at the <code class="literal">8080</code> 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 <code class="literal">8443</code>. </p></li><li><p>The second AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol. </p></li><li><p> |
| The engine has a logical name of <code class="literal">Catalina</code>; this is the name used in all log and error messages so you can easily identify problems. |
| The value of the <code class="literal">defaultHost</code> attribute refers to the name of a <code class="literal"><Host></code> child element of <code class="literal"><Engine></code>; this host processes requests directed to host names on this servlet container. |
| </p></li><li><p> |
| The <code class="literal"><Host></code> child element represents a virtual host, which is an association of a network name for a server (such as <code class="literal">www.mycompany.com</code>) with the particular server on which Catalina is running. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-connectors"></a>Connector Configuration</h3></div></div></div><p>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 <code class="literal"><Connector></code> implementations, consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html" target="_top">Tomcat HTTP Connector</a> documentation. |
| For detailed instructions on how to configure Tomcat's SSL support, consult the official <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html" target="_top">Tomcat SSL Configuration HOW-TO</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-clustering"></a>Cluster Configuration</h3></div></div></div><p> |
| 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 <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html" target="_top">Tomcat Clustering/Session Replication HOW-TO</a> for detailed information about enabling and configuring clustering. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-default-web-xml"></a>Default web.xml Configuration</h3></div></div></div><p> |
| Java Servlet specification enables web applications to provide deployment descriptor (<code class="literal">web.xml</code>) in the <code class="literal">WEB-INF</code> directory. |
| Apache Tomcat introduces a default <code class="literal">web.xml</code> which is similar to web application's <code class="literal">web.xml</code>, but provides configurations that are applied to all web applications. |
| When deploying a web application, Apache Tomcat uses the default <code class="literal">web.xml</code> file as a base configuration. |
| If the web application provides its own configurations via <code class="literal">web.xml</code> (the one located in the web application's <code class="literal">WEB-INF</code>) 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 <code class="literal">web.xml</code> file located in the <code class="literal">$GW_HOME/config</code> directory. |
| </p><p> |
| </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top">Be careful when changing/extending the default <code class="literal">web.xml</code> as this will affect all web applications.</td></tr></table></div><p> |
| </p><p> |
| Here's an extract of the default configuration distributed with the GW. |
| </p><pre class="programlisting"><<span class="hl-tag">?xml version="1.0" encoding="ISO-8859-1"?</span>> |
| <<span class="hl-tag">web-app</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://java.sun.com/xml/ns/javaee"</span> |
| <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span> |
| <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"</span> |
| <span class="hl-attribute">version</span>=<span class="hl-value">"3.0"</span>> |
| |
| <<span class="hl-tag">servlet</span>> |
| <<span class="hl-tag">servlet-name</span>>default<<span class="hl-tag">/servlet-name</span>> |
| <<span class="hl-tag">servlet-class</span>>org.apache.catalina.servlets.DefaultServlet<<span class="hl-tag">/servlet-class</span>> |
| <<span class="hl-tag">init-param</span>> |
| <<span class="hl-tag">param-name</span>>debug<<span class="hl-tag">/param-name</span>> |
| <<span class="hl-tag">param-value</span>>0<<span class="hl-tag">/param-value</span>> |
| <<span class="hl-tag">/init-param</span>> |
| <<span class="hl-tag">init-param</span>> |
| <<span class="hl-tag">param-name</span>>listings<<span class="hl-tag">/param-name</span>> |
| <<span class="hl-tag">param-value</span>>false<<span class="hl-tag">/param-value</span>> |
| <<span class="hl-tag">/init-param</span>> |
| <<span class="hl-tag">load-on-startup</span>>1<<span class="hl-tag">/load-on-startup</span>> |
| <<span class="hl-tag">/servlet</span>> |
| |
| <<span class="hl-tag">servlet</span>> |
| <<span class="hl-tag">servlet-name</span>>jsp<<span class="hl-tag">/servlet-name</span>> |
| <<span class="hl-tag">servlet-class</span>>org.apache.jasper.servlet.JspServlet<<span class="hl-tag">/servlet-class</span>> |
| <<span class="hl-tag">init-param</span>> |
| <<span class="hl-tag">param-name</span>>fork<<span class="hl-tag">/param-name</span>> |
| <<span class="hl-tag">param-value</span>>false<<span class="hl-tag">/param-value</span>> |
| <<span class="hl-tag">/init-param</span>> |
| <<span class="hl-tag">init-param</span>> |
| <<span class="hl-tag">param-name</span>>xpoweredBy<<span class="hl-tag">/param-name</span>> |
| <<span class="hl-tag">param-value</span>>false<<span class="hl-tag">/param-value</span>> |
| <<span class="hl-tag">/init-param</span>> |
| <<span class="hl-tag">load-on-startup</span>>3<<span class="hl-tag">/load-on-startup</span>> |
| <<span class="hl-tag">/servlet</span>> |
| |
| <<span class="hl-tag">servlet-mapping</span>> |
| <<span class="hl-tag">servlet-name</span>>default<<span class="hl-tag">/servlet-name</span>> |
| <<span class="hl-tag">url-pattern</span>>/<<span class="hl-tag">/url-pattern</span>> |
| <<span class="hl-tag">/servlet-mapping</span>> |
| |
| <<span class="hl-tag">servlet-mapping</span>> |
| <<span class="hl-tag">servlet-name</span>>jsp<<span class="hl-tag">/servlet-name</span>> |
| <<span class="hl-tag">url-pattern</span>>*.jsp<<span class="hl-tag">/url-pattern</span>> |
| <<span class="hl-tag">/servlet-mapping</span>> |
| |
| <<span class="hl-tag">servlet-mapping</span>> |
| <<span class="hl-tag">servlet-name</span>>jsp<<span class="hl-tag">/servlet-name</span>> |
| <<span class="hl-tag">url-pattern</span>>*.jspx<<span class="hl-tag">/url-pattern</span>> |
| <<span class="hl-tag">/servlet-mapping</span>> |
| |
| <<span class="hl-tag">session-config</span>> |
| <<span class="hl-tag">session-timeout</span>>30<<span class="hl-tag">/session-timeout</span>> |
| <<span class="hl-tag">/session-config</span>> |
| |
| <<span class="hl-tag">mime-mapping</span>> |
| <<span class="hl-tag">extension</span>>abs<<span class="hl-tag">/extension</span>> |
| <<span class="hl-tag">mime-type</span>>audio/x-mpeg<<span class="hl-tag">/mime-type</span>> |
| <<span class="hl-tag">/mime-mapping</span>> |
| ...... |
| <<span class="hl-tag">mime-mapping</span>> |
| <<span class="hl-tag">extension</span>>ppt<<span class="hl-tag">/extension</span>> |
| <<span class="hl-tag">mime-type</span>>application/vnd.ms-powerpoint<<span class="hl-tag">/mime-type</span>> |
| <<span class="hl-tag">/mime-mapping</span>> |
| |
| <<span class="hl-tag">welcome-file-list</span>> |
| <<span class="hl-tag">welcome-file</span>>index.html<<span class="hl-tag">/welcome-file</span>> |
| <<span class="hl-tag">welcome-file</span>>index.htm<<span class="hl-tag">/welcome-file</span>> |
| <<span class="hl-tag">welcome-file</span>>index.jsp<<span class="hl-tag">/welcome-file</span>> |
| <<span class="hl-tag">/welcome-file-list</span>> |
| |
| <<span class="hl-tag">/web-app</span>> |
| </pre><p> |
| The following bullets describe the main elements in the default <code class="literal">web.xml</code> file. |
| </p><div class="itemizedlist"><ul type="disc"><li><p>The <code class="literal"><Servlet></code> XML element declares a given servlet and its configurations. The sample <code class="literal">web.xml</code> file above includes two <Servlet> elements.</p><div class="itemizedlist"><ul type="circle"><li><p> |
| 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 <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html" target="_top">Apache Tomcat Default Servlet Reference.</a>. |
| </p></li><li><p> |
| 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 <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html" target="_top">Apache Tomcat Jasper 2 JSP Engine.</a>. |
| </p></li></ul></div></li><li><p>The <code class="literal"><servlet-mapping></code> XML element specifies the mapping between the servlet and URL pattern.</p></li><li><p> |
| The <code class="literal"><session-config></code> XML element defines the session configuration for one web application. |
| The sample <code class="literal">web.xml</code> file above specifies that the session timeout for all web applications will be 30 minutes by default. |
| </p></li><li><p> |
| The <code class="literal"><mime-mapping></code> 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. |
| </p></li><li><p> |
| The <code class="literal"><welcome-file-list></code> 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. |
| </p></li></ul></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-tomcat-contexts"></a>Context Configuration</h3></div></div></div><p> |
| Gemini Web Container supports standard Apache Tomcat web application context configuration. |
| The <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html" target="_top">Apache Tomcat Configuration Reference</a> has a section on |
| <a class="ulink" href="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html" target="_top">The Context Container</a> which describes the mechanism that |
| is used in GW for searching context configuration files and details the context configuration properties. |
| </p><p> |
| Context configuration files may be placed in the following locations, |
| where <code class="literal">[enginename]</code> is the name of Tomcat's engine ('Catalina' by default) and <code class="literal">[hostname]</code> names |
| a virtual host ('localhost' by default), both of which are configured in <code class="literal">tomcat-server.xml</code>: |
| </p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">$GW_HOME/config/context.xml</code> provides the default context configuration file for all web applications.</p></li><li><p> |
| The <code class="literal">$GW_HOME/config/[enginename]/[hostname]</code> directory may contain: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| The default context configuration for all web applications of a given virtual host in the file <code class="literal">context.xml.default</code>. |
| </p></li><li><p> |
| 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 <code class="literal">foo</code> may be configured in <code class="literal">foo.xml</code>. |
| </p></li></ul></div><p> |
| </p></li></ul></div><p> |
| </p><p> |
| Note that the following context configuration features are not supported in Gemini Web Container: |
| </p><div class="itemizedlist"><ul type="disc"><li><p>Custom class loaders.</p></li><li><p>Specifying the context path. This is specified using the <code class="literal">Web-ContextPath</code> header in the web application's <code class="literal">MANIFEST.MF</code> file.</p></li><li><p>Specifying the document base directory.</p></li></ul></div><p> |
| </p></div></div></div><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript"> |
| _lf_cid = "LF_48be82fa"; |
| _lf_remora(); |
| </script><!--End LoopFuse code--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s02.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch03s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.2 Installing from the ZIP Download </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.2 Configuring the OSGi Framework</td></tr></table></div></body></html> |
