| <?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><Server></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><Listener></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><Service></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><Service></literal> element can have many <literal><Connector></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><Engine></literal> element for any given <literal><Service></literal> element.</para> |
| <para>The sample <literal>tomcat-server.xml</literal> file above includes two <literal><Connector></literal> elements: one for the HTTP transport, and one for the AJP transport. The file also includes a single <literal><Engine></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><Host></literal> child element of <literal><Engine></literal>; this host processes requests directed to host names on this servlet container. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The <literal><Host></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><Host></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><Connector></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><Servlet></literal> XML element declares a given servlet and its configurations. The sample <literal>web.xml</literal> file above includes two <Servlet> 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><servlet-mapping></literal> XML element specifies the mapping between the servlet and URL pattern.</para> |
| </listitem> |
| <listitem> |
| <para> |
| The <literal><session-config></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><mime-mapping></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><welcome-file-list></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> |
| <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> |
| </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> |
