<path id="doc.bundles">

		<pathelement location="../org.eclipse.gemini.web.documentation/user-guide"/>

		<pathelement location="../org.eclipse.gemini.web.documentation/programmer-guide"/>

	</path>

		<all-bundles target="package" buildpathRef="doc.bundles">

			<property name="package.output.dir" value="${package.output.dir}"/>

		</all-bundles>

	<target name="doc">

		<all-bundles target="doc" buildpathRef="doc.bundles"/>

	</target>

	<target name="doc-html">

		<all-bundles target="doc-html" buildpathRef="doc.bundles"/>

	</target>

version=1.2.0

release.type=integration

javadoc.exclude.package.names=**/internal/**,**/internal

ivy.cache=ivy-cache

ivy.cache.dir=${basedir}/../../${ivy.cache}

integration.repo.dir=${basedir}/../../integration-repo

findbugs.enforce=true

clover.enforce=true

clover.coverage=40%

local.repository.dir=${basedir}/../../ivy-repository

project.name=Gemini Web

natural.name=gemini-web

project.key=GW

<?xml version="1.0" encoding="UTF-8"?>

<project name="gemini-web-programmer-guide">

	<property file="${basedir}/../build.properties"/>

	<property file="${basedir}/../../build.versions"/>

	<import file="${basedir}/../../virgo-build/docbook/default.xml"/>

	<filterset id="docbook.filters">

		<filter token="bundle.version" value="${bundle.version}"/>

		<filtersfile file="${basedir}/filters.properties"/>

	</filterset>

</project>

project.name=Gemini Web

product.name=Gemini Web Container

short.product.name=GW

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>

<ivy-module

		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

		xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"

		version="1.3">

	<info organisation="org.eclipse.gemini.web" module="${ant.project.name}"/>

	<configurations>

		<include file="${virgo.build.dir}/common/default-ivy-configurations.xml"/>

		<conf name="doc" visibility="public" description="Documentation"/>

	</configurations>

	<publications>

		<artifact name="${ant.project.name}" ext="zip" type="zip"/>

		<artifact name="${ant.project.name}-single" ext="zip" type="zip"/>

	</publications>

	<dependencies/>

</ivy-module>

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<book xmlns:xi="http://www.w3.org/2001/XInclude">

	<bookinfo>

		<title>@project.name@ User Guide</title>

		<titleabbrev>User Guide</titleabbrev>

		<productname>@project.name@</productname>

		<releaseinfo>@bundle.version@</releaseinfo>

	</bookinfo>

	<toc />

	<xi:include href="introduction.xml"/>

</book>

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="introduction">

	<title>Overview</title>

	<section id="intro">

		<title>Introduction</title>

		<para>

			@product.name@ implements the Web Container defined by the Web Applications Specification chapter of the OSGi Service Platform Release 4 Version 4.2 Enterprise Specification. 

			This specification may be downloaded <ulink url="http://www.osgi.org/Download/Release4V42">here</ulink>.

		</para>

	</section>

</chapter>

<?xml version="1.0" encoding="UTF-8"?>

<project name="gemini-web-user-guide">

	<property file="${basedir}/../build.properties"/>

	<property file="${basedir}/../../build.versions"/>

	<import file="${basedir}/../../virgo-build/docbook/default.xml"/>

	<filterset id="docbook.filters">

		<filter token="bundle.version" value="${bundle.version}"/>

		<filtersfile file="${basedir}/filters.properties"/>

	</filterset>

</project>

project.name=Gemini Web

product.name=Gemini Web Container

short.product.name=GW

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>

<ivy-module

		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

		xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"

		version="1.3">

	<info organisation="org.eclipse.gemini.web" module="${ant.project.name}"/>

	<configurations>

		<include file="${virgo.build.dir}/common/default-ivy-configurations.xml"/>

		<conf name="doc" visibility="public" description="Documentation"/>

	</configurations>

	<publications>

		<artifact name="${ant.project.name}" ext="zip" type="zip"/>

		<artifact name="${ant.project.name}-single" ext="zip" type="zip"/>

	</publications>

	<dependencies/>

</ivy-module>

<?xml version="1.0" encoding="utf-8"?>

<chapter id="configuring">

	<title>Configuration</title>

	<titleabbrev>Configuration</titleabbrev>

	<section id="configuring-tomcat">

		<title>Configuring the Embedded Tomcat Servlet Container</title>

		<para>

			@product.name@

			embeds an OSGi-enhanced version of the <ulink url="http://tomcat.apache.org/">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>.  

			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" />

  <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />

  <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="true" xmlValidation="false" xmlNamespaceAware="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-6.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 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 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 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.  

						The <literal>xmlValidation</literal> attribute specifies that the servlet container does not validate XML files when parsing them, or in other words, it accepts invalid XML. 

						The <literal>xmlNamespaceAware</literal> attribute specifies that the servlet container does not take namespaces into account when reading XML files. 

					</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-6.0-doc/config/http.html">Tomcat HTTP Connector</ulink> documentation.

				For detailed instructions on how to configure Tomcat's SSL support, consult the official <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">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-6.0-doc/cluster-howto.html">Tomcat Clustering/Session Replication HOW-TO</ulink> for detailed information about enabling and configuring clustering.

			</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-6.0-doc/config/index.html">Apache Tomcat Configuration Reference</ulink> has a section on

					<ulink url="http://tomcat.apache.org/tomcat-6.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 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>

	<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.

								</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>

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<book xmlns:xi="http://www.w3.org/2001/XInclude">

	<bookinfo>

		<title>@project.name@ User Guide</title>

		<titleabbrev>User Guide</titleabbrev>

		<productname>@product.name@</productname>

		<releaseinfo>@bundle.version@</releaseinfo>

		<legalnotice>

			<para>

				Copyright © 2009, 2010 VMware Inc. and others

			</para>

			<para>

				Contributors:

				<itemizedlist>

					<listitem>

						<para>

							VMware Inc. - initial contribution

						</para>

					</listitem>

					<listitem>

						<para>

							Violeta Georgieva, SAP AG - Tomcat context configuration

						</para>

					</listitem>

				</itemizedlist>

			</para>

		</legalnotice>

	</bookinfo>

	<toc />

	<xi:include href="introduction.xml" />

	<xi:include href="installing.xml" />

	<xi:include href="configuring.xml" />

</book>

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="installation">

	<title>Installing @project.name@</title>

	<section id="installation-prereqs">

		<title>Prerequisites</title>

		<para>

			The @product.name@, or @short.product.name@ for short, requires Java SE 6 or later to be installed. Java is available from

			<ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.

		</para>

	</section>

	<section id="installation-zip">

		<title>Installing from the ZIP Download</title>

		<section>

			<itemizedlist>

				<listitem>

					<para>

						<ulink url="http://download.eclipse.org/equinox/">Download</ulink> the Equinox JAR, for example <ulink url="http://download.eclipse.org/equinox/drops/R-3.6-201006080911/download.php?dropFile=org.eclipse.osgi_3.6.0.v20100517.jar">org.eclipse.osgi_3.6.0.v20100517.jar</ulink>, and move it to a suitable directory (e.g. ~/gemini-web-test). 

						On the <ulink url="http://download.eclipse.org/equinox/">Download</ulink> page, first choose the desired Release or Build, then download the JAR from the Framework section. 

					</para>

				</listitem>

				<listitem>

					<para>

						@product.name@ is distributed as a ZIP file.

						<ulink url="http://www.eclipse.org/gemini/web/download">Download</ulink> @product.name@ and unzip it to ~/gemini-web-test/gemini-web. 

					</para>

				</listitem>

				<listitem>

					<para>

						Configure Equinox by creating a directory ~/gemini-web-test/configuration and create files config.ini and Java6-server.profile in the configuration directory. 

						Example files which work with 1.1.0.RELEASE are available in <ulink url="http://wiki.eclipse.org/images/5/5e/Config.ini.zip">config.ini.zip</ulink> and <ulink url="http://wiki.eclipse.org/images/3/32/Java6-server.profile.zip">Java6-server.profile.zip</ulink>. 

						Essentially config.ini ensures that Java6-server.profile is used and that the dependencies of @product.name@, which come in the dep directory, are installed and then the @product.name@ bundles are installed and started. 

						Java6-server.profile ensures that javax.xml.ws is exported at version 2.1.1 from the system bundle as the Tomcat bundles in @product.name@ depend on that version. 

					</para>

				</listitem>

				<listitem>

					<para>

						Start Equinox as follows:

						<programlisting language="xml"><![CDATA[java -jar org.eclipse.osgi_3.6.0.v20100517.jar -console]]></programlisting></para>

				</listitem>

				<listitem>

					<para>

						You can then deploy WAR files (a trivial example is available in <ulink url="http://wiki.eclipse.org/images/a/a0/Simple-war.war.zip">Simple-war.war.zip</ulink>) and web bundles using the install and start commands from the console.

						<programlisting language="xml"><![CDATA[osgi> install file:simple-war.war

Bundle id is 40

osgi> start 40]]></programlisting></para>

				</listitem>

				<listitem>

					<para>

						Drive the WAR or web bundle using a web browser, e.g. http://localhost:8080/simple-war should display "Hello World!". 

					</para>

				</listitem>

				<listitem>

					<para>

						Stop @product.name@ as follows:

						<programlisting language="xml"><![CDATA[osgi> close]]></programlisting>

						<tip>

							You need to stop any old instance of Gemini Web before starting it again. Otherwise, the new instance will not start correctly, because the old one still occupies the http port (and, perhaps, other system resources).

						</tip>

					</para>

				</listitem>

			</itemizedlist>

		</section>

	</section>

</chapter>

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="introduction">

	<title>Overview</title>

	<section id="intro">

		<title>Introduction</title>

		<para>

			@product.name@ implements the Web Container defined by the Web Applications Specification chapter of the OSGi Service Platform Release 4 Version 4.2 Enterprise Specification. 

			This specification may be downloaded <ulink url="http://www.osgi.org/Download/Release4V42">here</ulink>.

		</para>

	</section>

	<section id="about-this-guide">

		<title>About This Guide</title>

		<para>

			This User Guide contains step-by-step instructions on how to use @product.name@. This User Guide will enable you to:

			<itemizedlist>

				<listitem>

					<para>

						Install @product.name@

					</para>

				</listitem>

				<listitem>

					<para>

						Deploy and request a simple web application

					</para>

				</listitem>

				<listitem>

					<para>

						Configure Tomcat

					</para>

				</listitem>

			</itemizedlist>

		</para>

	</section>

</chapter>