<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->
<document xmlns="http://maven.apache.org/XDOC/2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
        <title>HTTP servlet transport</title>
    </properties>
    <body>
        <h1>HTTP servlet transport</h1>
        <section name="Introduction">
            <p>
                The servlet transport processes HTTP requests received through the servlet
                container in which Axis2 is deployed. It is different from the other transports
                because its lifecycle is not managed by Axis2, but by the servlet container.
                Two things are necessary to enable and configure the servlet transport: 
            </p>
            <ul>
                <li>
                    <tt>org.apache.axis2.transport.http.AxisServlet</tt> must be registered
                    and mapped as a servlet in <tt>web.xml</tt>.
                </li>
                <li>
                    One or more <tt>org.apache.axis2.transport.http.AxisServletListener</tt>
                    instances must be declared as transport receivers in <tt>axis2.xml</tt>.
                </li>
            </ul>
            <p>
                It should be noted that the role of <tt>AxisServlet</tt> is not limited to that
                of an Axis2 transport, but that it provides two additional features:
            </p>
            <ul>
                <li>
                    It starts the Axis2 runtime and sets it up to load the <tt>axis2.xml</tt>
                    configuration as well as the repository from the Web application.
                </li>
                <li>
                    It exposes the WSDL documents of deployed services. The WSDL of a service can be
                    accessed by appending <tt>?wsdl</tt> to the EPR of the service.
                </li>
            </ul>
        </section>
        <section name="Adding AxisServlet to web.xml">
            <p>
                <tt>AxisServlet</tt> is typically configured as follows in <tt>web.xml</tt>:
            </p>
<pre><![CDATA[
    <servlet>
        <servlet-name>AxisServlet</servlet-name>
        <display-name>Apache-Axis Servlet</display-name>
        <servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>AxisServlet</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping>
]]></pre>
            <p>
                Note that the prefix used in <tt>url-pattern</tt> must match the
                <tt>servicePath</tt> parameter in <tt>axis2.xml</tt>. The default
                value of this parameter is <tt>services</tt>, which is compatible
                with the above configuration.
            </p>
        </section>
        <section name="Configuring axis2.xml">
            <p>
                For each protocol (HTTP and/or HTTPS), an <tt>AxisServletListener</tt>
                instance must be declared in <tt>axis2.xml</tt>. If only a single
                protocol is used, no further configuration is required. For example,
                if only HTTP is used, the following declaration must be present in
                <tt>axis2.xml</tt>:
            </p>
<pre><![CDATA[
<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"/>
]]></pre>
            <p>
                If both HTTP and HTTPS are used, then things become a bit more complicated.
                The reason is that in order to expose WSDLs with correct endpoint URIs,
                <tt>AxisServlet</tt> must know the ports used by HTTP and HTTPS.
                Unfortunately the servlet API doesn't allow a Web application to discover
                all configured protocols. It only provides information about the protocol,
                host name and port for the current request. If only a single
                <tt>AxisServletListener</tt> is configured, then this information is enough
                to let <tt>AxisServlet</tt> auto-detect the port number. If both HTTP
                and HTTPS are used (or if WSDLs are retrieved through transports other than
                <tt>AxisServlet</tt>), then <tt>AxisServlet</tt> has no way of knowing the
                port numbers until it has processed at least one request
                for each protocol. To make WSDL generation predictable in this scenario, it
                is necessary to explicitly configure the port numbers in <tt>axis2.xml</tt>,
                such as in the following example:
            </p>
<pre><![CDATA[
<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener">
    <parameter name="port">8080</parameter>
</transportReceiver>

<transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServletListener">
    <parameter name="port">8443</parameter>
</transportReceiver>
]]></pre>
        </section>
    </body>
</document>