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