HTTP servlet transport

Introduction

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:

  • org.apache.axis2.transport.http.AxisServlet must be registered and mapped as a servlet in web.xml.
  • One or more org.apache.axis2.transport.http.AxisServletListener instances must be declared as transport receivers in axis2.xml.

It should be noted that the role of AxisServlet is not limited to that of an Axis2 transport, but that it provides two additional features:

  • It starts the Axis2 runtime and sets it up to load the axis2.xml configuration as well as the repository from the Web application.
  • It exposes the WSDL documents of deployed services. The WSDL of a service can be accessed by appending ?wsdl to the EPR of the service.

Adding AxisServlet to web.xml

AxisServlet is typically configured as follows in web.xml: 

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

Note that the prefix used in url-pattern must match the servicePath parameter in axis2.xml. The default value of this parameter is services, which is compatible with the above configuration.

Configuring axis2.xml

For each protocol (HTTP and/or HTTPS), an AxisServletListener instance must be declared in axis2.xml. 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 axis2.xml: 

<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"/>

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, AxisServlet 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 AxisServletListener is configured, then this information is enough to let AxisServlet auto-detect the port number. If both HTTP and HTTPS are used (or if WSDLs are retrieved through transports other than AxisServlet), then AxisServlet 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 axis2.xml, such as in the following example: 

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