path: root/org.eclipse.gemini.web.documentation/user-guide/src/configuring.xml

<?xml version="1.0" encoding="utf-8"?>
<chapter id="configuring">
	<title>Configuration</title>
	<titleabbrev>Configuration</titleabbrev>
	<section id="configuring-tomcat">
		<title>Configuring the Embedded Apache Tomcat Servlet Container</title>
		<para>
			@product.name@
			embeds an OSGi-enhanced version of the <ulink url="http://tomcat.apache.org/">Apache Tomcat Servlet Container</ulink>
			in order to provide support for deploying Java EE WARs and OSGi <emphasis>Web Application Bundles</emphasis>. 
			You configure the embedded Servlet container using the standard Apache Tomcat configuration.
			The main difference is that the configuration file is called <filename>tomcat-server.xml</filename> rather than <literal>server.xml</literal>.  
			Another difference is that not all standard Apache Tomcat configuration is supported in @product.name@: the restrictions are described in the remainder of this section.
			If you do not want to use the default settings, you can provide the <literal>tomcat-server.xml</literal> file located in the <literal>$GW_HOME/config</literal> directory. 
		</para>
		<para>Here's an extract of the default configuration distributed with the @short.product.name@.</para>
		<programlisting language="xml"><![CDATA[<?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>]]></programlisting>
		<section id="overview-tomcat-servlet-container">
			<title>Description of the Default Apache Tomcat Configuration</title>
			<para>
				The following bullets describe the main elements and attributes in the default <literal>tomcat-server.xml</literal> file; for details about updating this file to further configure the embedded Apache Tomcat server, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</ulink>.
			</para>
			<tip>
				<title>Relative paths</title>
				<para>If the configured path to a directory or file does not represent an absolute path, @short.product.name@ typically interprets it as a path relative to the <filename>$GW_HOME</filename> directory.</para>
			</tip>
			<itemizedlist>
				<listitem>
					<para>The root element of the <literal>tomcat-server.xml</literal> file is <literal>&lt;Server&gt;</literal>. The attributes of this element represent the characteristics of the entire embedded Apache Tomcat servlet container. The <literal>shutdown</literal> 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 <literal>port</literal> attribute specifies the TCP/IP port number that listens for a shutdown message.</para>
				</listitem>
				<listitem>
					<para>The <literal>&lt;Listener&gt;</literal> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Apache 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.</para>
				</listitem>
				<listitem>
					<para>The <literal>&lt;Service&gt;</literal> 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 <literal>&lt;Service&gt;</literal> element can have many <literal>&lt;Connector&gt;</literal> 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 <literal>&lt;Engine&gt;</literal> element for any given <literal>&lt;Service&gt;</literal> element.</para>
					<para>The sample <literal>tomcat-server.xml</literal> file above includes two <literal>&lt;Connector&gt;</literal> elements: one for the HTTP transport, and one for the AJP transport. The file also includes a single <literal>&lt;Engine&gt;</literal> element, as required.</para>
				</listitem>
				<listitem>
					<para>The first connector listens for HTTP requests at the <literal>8080</literal> 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 <literal>8443</literal>. </para>
				</listitem>
				<listitem>
					<para>The second AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol. </para>
				</listitem>
				<listitem>
					<para>
						The engine has a logical name of <literal>Catalina</literal>; this is the name used in all log and error messages so you can easily identify problems. 
						The value of the <literal>defaultHost</literal> attribute refers to the name of a <literal>&lt;Host&gt;</literal> child element of <literal>&lt;Engine&gt;</literal>; this host processes requests directed to host names on this servlet container.
					</para>
				</listitem>
				<listitem>
					<para>
						The <literal>&lt;Host&gt;</literal> child element represents a virtual host, which is an association of a network name for a server (such as <literal>www.mycompany.com</literal>) with the particular server on which Catalina is running.  
					</para>
				</listitem>
				<listitem>
					<para>
						Note that multiple <literal>&lt;Host&gt;</literal> elements are not supported in @product.name@.
					</para>
				</listitem>
			</itemizedlist>
		</section>
		<section id="configuring-tomcat-connectors">
			<title>Connector Configuration</title>
			<para>The @product.name@ 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 <literal>&lt;Connector&gt;</literal> implementations, consult the official <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/http.html">Apache Tomcat HTTP Connector</ulink> documentation.
				For detailed instructions on how to configure Apache Tomcat's SSL support, consult the official <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html">Apache Tomcat SSL Configuration HOW-TO</ulink>.
			</para>
		</section>
		<section id="configuring-tomcat-clustering">
			<title>Cluster Configuration</title>
			<para>
				@product.name@ 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 <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html">Apache Tomcat Clustering/Session Replication HOW-TO</ulink> for detailed information about enabling and configuring clustering.
			</para>
		</section>
		<section id="configuring-default-web-xml">
			<title>Default web.xml Configuration</title>
			<para>
				Java Servlet specification enables web applications to provide deployment descriptor (<literal>web.xml</literal>) in the <literal>WEB-INF</literal> directory.
				Apache Tomcat introduces a default <literal>web.xml</literal> which is similar to web application's <literal>web.xml</literal>, but provides configurations that are applied to all web applications.
				When deploying a web application, Apache Tomcat uses the default <literal>web.xml</literal> file as a base configuration. 
				If the web application provides its own configurations via <literal>web.xml</literal> (the one located in the web application's <literal>WEB-INF</literal>) or annotations, they overwrite the default ones.
				In @product.name@ you can also provide default configurations for all web applications.
				If you want to change/extend the default configurations, you can provide the default <literal>web.xml</literal> file located in the <literal>$GW_HOME/config</literal> directory. 
			</para>
			<para>
				<tip>Be careful when changing/extending the default <literal>web.xml</literal> as this will affect all web applications.</tip>
			</para>
			<para>
				Here's an extract of the default configuration distributed with the @short.product.name@.
			</para>
			<programlisting language="xml"><![CDATA[<?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>
]]></programlisting>
			<para>
				The following bullets describe the main elements in the default <literal>web.xml</literal> file.
				<itemizedlist>
					<listitem>
						<para>The <literal>&lt;Servlet&gt;</literal> XML element declares a given servlet and its configurations. The sample <literal>web.xml</literal> file above includes two &lt;Servlet&gt; elements.</para>
						<itemizedlist>
							<listitem>
								<para>
									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 <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/default-servlet.html">Apache Tomcat Default Servlet Reference.</ulink>.
								</para>
							</listitem>
							<listitem>
								<para>
									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 <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine.</ulink>.
								</para>
							</listitem>
						</itemizedlist>
					</listitem>
					<listitem>
						<para>The <literal>&lt;servlet-mapping&gt;</literal> XML element specifies the mapping between the servlet and URL pattern.</para>
					</listitem>
					<listitem>
						<para>
							The <literal>&lt;session-config&gt;</literal> XML element defines the session configuration for one web application. 
							The sample <literal>web.xml</literal> file above specifies that the session timeout for all web applications will be 30 minutes by default.
						</para>
					</listitem>
					<listitem>
						<para>
							The <literal>&lt;mime-mapping&gt;</literal> 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.
						</para>
					</listitem>
					<listitem>
						<para>
							The <literal>&lt;welcome-file-list&gt;</literal> 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.
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
		<section id="configuring-tomcat-contexts">
			<title>Context Configuration</title>
			<para>
				@product.name@ supports standard Apache Tomcat web application context configuration.
				The <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/index.html">Apache Tomcat Configuration Reference</ulink> has a section on
				<ulink url="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html">The Context Container</ulink> which describes the mechanism that
				is used in @short.product.name@ for searching context configuration files and details the context configuration properties.
			</para>
			<para>
				Context configuration files may be placed in the following locations,
				where <literal>[enginename]</literal> is the name of Apache Tomcat's engine ('Catalina' by default) and <literal>[hostname]</literal> names
				a virtual host ('localhost' by default), both of which are configured in <literal>tomcat-server.xml</literal>:
				<itemizedlist>
					<listitem>
						<para><literal>$GW_HOME/config/context.xml</literal> provides the default context configuration file for all web applications.</para>
					</listitem>
					<listitem>
						<para>
							The <literal>$GW_HOME/config/[enginename]/[hostname]</literal> directory may contain:
					  		<itemizedlist>
								<listitem>
									<para>
										The default context configuration for all web applications of a given virtual host in the file <literal>context.xml.default</literal>.
									</para>
								</listitem>
								<listitem>
									<para>
										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 <literal>foo</literal> may be configured in <literal>foo.xml</literal>.
									</para>
								</listitem>
							</itemizedlist>
						</para>
					</listitem>
				</itemizedlist>
			</para>
			<para>
				Note that the following context configuration features are not supported in @product.name@:
				<itemizedlist>
					<listitem>
						<para>Custom class loaders.</para>
					</listitem>
					<listitem>
						<para>Specifying the context path. This is specified using the <literal>Web-ContextPath</literal> header in the web application's <literal>MANIFEST.MF</literal> file.</para>
					</listitem>
					<listitem>
						<para>Specifying the document base directory.</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
		<section id="configuring-naming">
			<title>JNDI Resources</title>
			<para>
				By default @product.name@ supports standard Apache Tomcat JNDI Resources handling.
				The <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/jndi-resources-howto.html">Apache Tomcat JDNI Resources How-To</ulink> 
				describes in details how the JNDI resources can be configured and used.
			</para>
			<para>
				In addition to that feature @product.name@ provides a possibility to switch off the standard Apache Tomcat JNDI Resources handling or to use the OSGi one.
				One can specify the preferred option using <literal>-DuseNaming</literal> with one of the following options:
				<itemizedlist>
					<listitem><literal>tomcat</literal> - the default value: this is the standard Apache Tomcat JNDI Resources handling.</listitem>
					<listitem><literal>disabled</literal> - there is no JNDI Resources handling provided by @product.name@.</listitem>
					<listitem>
						<literal>osgi</literal> - the OSGi JNDI Resource handling will be enabled. 
						(<ulink url="http://eclipse.org/gemini/naming/">Gemini Naming</ulink> can be used as implementation for OSGi JNDI Services Specification)
						The <ulink url="http://www.osgi.org/download/r4v42/r4.enterprise.pdf">OSGi JNDI Services Specification</ulink>
						describes in details how JNDI can be utilized from within an OSGi framework.
						One can use either <literal>osgi URL scheme</literal> in order to look up an OSGi service, or <literal>java URL scheme</literal> - a feature provided by @product.name@.
						If <literal>java URL scheme</literal> is chosen then additional configuration is necessary to be provided via context.xml.
<programlisting language="xml"><![CDATA[<Context>
<Resource name="LogService"
          type="org.osgi.service.log.LogService"
          mappedName="service/org.osgi.service.log.LogService"
          factory="org.eclipse.gemini.web.tomcat.naming.factory.OsgiServiceFactory"/>
</Context>]]></programlisting>
						The list below describes in details the different properties:
						<itemizedlist>
							<listitem><literal>name</literal> - The name of the resource that will be created. The name should be relative to the java:comp/env context.</listitem>
							<listitem><literal>type</literal> - The fully qualified Java class name of the resource (OSGi service) that web application will expect when it performs a lookup or when it uses @Resource annotation.</listitem>
							<listitem>
								<literal>mappedName</literal> - the service/s that should be looked up and the filter details if any. 
								The syntax can be seen in <ulink url="http://www.osgi.org/download/r4v42/r4.enterprise.pdf">OSGi JNDI Services Specification: 126.6 OSGi URL Scheme</ulink>.
							</listitem>
							<listitem><literal>factory</literal> - The class name for the JNDI object factory. @product.name@ provides a special JNDI object factory in order to be able to obtain an OSGi service.</listitem>
						</itemizedlist>
					</listitem>
				</itemizedlist>
			</para>
		</section>
		<section id="configuring-jsp-compilation">
			<title>JSP Compilation</title>
			<para>
				By default Apache Tomcat compiles JSP files in web applications agains Java 1.6.
				In order to enable JSP compilation against Java 1.7 for your web application,
				additional init parameters (<literal>compilerSourceVM</literal> and <literal>compilerTargetVM</literal>) should be added for the <literal>org.apache.jasper.servlet.JspServlet</literal> configuration.
				For details about <literal>org.apache.jasper.servlet.JspServlet</literal> configuration, see the <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/jasper-howto.html">Apache Tomcat Jasper 2 JSP Engine</ulink>.
				<literal>org.apache.jasper.servlet.JspServlet</literal> configuration can be provided with the web application's web.xml.
			</para>
			<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
<servlet>
    <servlet-name>jsp</servlet-name>
    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
    <init-param>
        <param-name>compilerSourceVM</param-name>
        <param-value>1.7</param-value>
    </init-param>
    <init-param>
        <param-name>compilerTargetVM</param-name>
        <param-value>1.7</param-value>
    </init-param>
    <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>jsp</servlet-name>
    <url-pattern>*.jsp</url-pattern>
    <url-pattern>*.jspx</url-pattern>
</servlet-mapping>
]]></programlisting>
		</section>
	</section>
	<section id="configuring-osgi-framework">
		<title>Configuring the OSGi Framework</title>
		<para>
			This section provides information about configuring the OSGi framework by updating the following files in the
			<literal>$GW_HOME/configuration</literal> directory:
		</para>
		<table id="configuring-osgi-framework-table" colsep="1" frame="all" rowsep="1">
			<title>OSGi Framework Configuration Files </title>
			<tgroup cols="2">
				<thead>
					<row>
						<entry>Property File</entry>
						<entry>Description</entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>
							<literal>config.ini</literal>
						</entry>
						<entry>Configures the <link linkend="configuring-framework-properties">OSGi framework properties</link>.</entry>
					</row>
					<row>
						<entry>
							<literal>java6-server.profile</literal>
						</entry>
						<entry>Configures the <link linkend="configuring-framework-profile">OSGi framework profile</link>.</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<section id="configuring-framework-properties">
			<title>Configuring OSGi Framework Properties</title>
			<para>
				You specify the framework properties in the <literal>$GW_HOME/configuration/config.ini</literal> file. 
				The properties relevant to users are described in the following table.
			</para>
			<table id="configuring-framework-properties-table" colsep="1" frame="all" rowsep="1">
				<title>Framework Properties</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Property</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>
								<literal>osgi.bundles</literal>
							</entry>
							<entry>
								The comma-separated list of bundles which are automatically installed and optionally started once the system is up and running.
							</entry>
						</row>
						<row>
							<entry>
								<literal>osgi.java.profile</literal>
							</entry>
							<entry>
								Specifies the profile to use using a <literal>file:</literal> URI with default value
								<literal>file:configuration/java6-server.profile</literal>.
							</entry>
						</row>
						<row>
							<entry>
								<literal>osgi.bundlefile.limit</literal>
							</entry>
							<entry>
								Specifies a limit on the number of jar files the framework will keep open.
								The minimum value allowed is 10. Any value less than 10 will disable the bundle file limit, making the the number of jar files the framework keeps open unlimited.
								By default the value is 100.
								Increase the default value if you have many jar files in the bundle class path, expect a lot of file system operations etc.
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</section>
		<section id="configuring-framework-profile">
			<title>Configuring OSGi Framework Profile</title>
			<para>
				You specify the framework profile in the <literal>$GW_HOME/configuration/java6-server.profile</literal> file. 
				The properties relevant to users are described in the following table.
			</para>
			<para>
				<emphasis role="bold">WARNING:</emphasis> We advise you not to change the framework profile unless you are sure you know exactly what
				you are doing; updating the profile could cause @short.product.name@ to fail.
			</para>
			<table id="configuring-framework-profile-table" colsep="1" frame="all" rowsep="1">
				<title>Framework Profile Properties</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Property</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>
								<literal>org.osgi.framework.bootdelegation</literal>
							</entry>
							<entry>
								<para>
									This property specifies the packages which are loaded by delegation to the application class loader.
									Bundles can load classes belonging to these packages without importing the packages.
									The <literal>.*</literal> wildcard matches any package suffix. 
									<literal>java.*</literal> is always boot delegated and must not be specified in this property.
									Note that the ordering of the packages does not matter.
								</para>
							</entry>
						</row>
						<row>
							<entry>
								<literal>org.osgi.framework.system.packages</literal>
							</entry>
							<entry>
								<para>
									This property specifies the packages which are exported by the system bundle.
								</para>
								<para>
									It is very occasionally necessary to extend the set, for example when configuring email logging appenders since the implementation of <literal>javax.mail</literal>	is intimately related to the implementation of <literal>javax.activation</literal>.
								</para>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</section>
	</section>
</chapter>