src/site/xdoc/docs/servlet-transport.xml - axis-axis2-java-core - Git at Google

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