cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > Server HTTP Transport
Date Sat, 01 Jan 2011 09:10:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Server+HTTP+Transport">Server
HTTP Transport</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~ffang">Freeman
Fang</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >|{{SuppressClientSendErrors}}|Specifies
whether exceptions are to be thrown when an error is encountered on receiving a request. The
default is {{false}}; exceptions are thrown on encountering errors.| <br>|{{SuppressClientReceiveErrors}}|Specifies
whether exceptions are to be thrown when an error is encountered on sending a response to
a client. The default is {{false}}; exceptions are thrown on encountering errors.| <br></td></tr>
            <tr><td class="diff-changed-lines" >|{{HonorKeepAlive}}|Specifies
whether the server honors requests for a connection to remain open after a response has been
sent. The default is <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{{false}};</span>
<span class="diff-added-words"style="background-color: #dfd;">{{true}};</span>
keep-alive requests are <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ignored.|</span>
<span class="diff-added-words"style="background-color: #dfd;">honored.|</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >|{{RedirectURL}}|Specifies the URL
to which the client request should be redirected if the URL specified in the client request
is no longer appropriate for the requested resource. In this case, if a status code is not
automatically set in the first line of the server response, the status code is set to 302
and the status description is set to Object Moved. The value is used as the value of the HTTP
{{RedirectURL}} property.| <br>|{{CacheControl}}|Specifies directives about the behavior
that must be adhered to by caches involved in the chain comprising a response from a server
to a client.| <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="ServerHTTPTransport-ServerHTTPTransport"></a>Server
HTTP Transport</h1>

<p>HTTP server endpoints can specify a number of HTTP connection attributes including
if it will honor keep alive requests, how it interacts with caches, and how tolerant it is
of errors in communicating with a consumer.</p>

<p>A server endpoint can be configured using two mechanisms:</p>

<ul>
	<li>Configuration</li>
	<li>WSDL</li>
</ul>


<h2><a name="ServerHTTPTransport-UsingConfiguration"></a>Using Configuration</h2>
<h3><a name="ServerHTTPTransport-Namespace"></a>Namespace</h3>

<p>The elements used to configure an HTTP provider endpoint are defined in the namespace
<tt><a href="http://cxf.apache.org/transports/http/configuration" class="external-link"
rel="nofollow">http://cxf.apache.org/transports/http/configuration</a></tt>.
It is commonly referred to using the prefix <tt>http-conf</tt>. In order to use
the HTTP configuration elements you will need to add the lines shown below to the beans element
of your endpoint's configuration file. In addition, you will need to add the configuration
elements' namespace to the <tt>xsi:schemaLocation</tt> attribute.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Adding the Configuration Namespace</b></div><div
class="codeContent panelContent">
<pre class="code-java">
&lt;beans ...
       xmlns:http-conf="http:<span class="code-comment">//cxf.apache.org/transports/http/configuration
</span>       ...
       xsi:schemaLocation="...
                           http:<span class="code-comment">//cxf.apache.org/transports/http/configuration
</span>                              http:<span class="code-comment">//cxf.apache.org/schemas/configuration/http-conf.xsd
</span>                          ...&gt;
</pre>
</div></div>

<h3><a name="ServerHTTPTransport-The%7B%7Bdestination%7D%7Delement"></a>The
<tt>destination</tt> element</h3>

<p>You configure an HTTP server endpoint using the <tt>http-conf:destination</tt>
element and its children. The <tt>http-conf:destination</tt> element takes a single
attribute, <tt>name</tt>, the specifies the WSDL port element that corresponds
to the endpoint. The value for the <tt>name</tt> attribute takes the form <em>portQName</em><tt>.http-destination</tt>.
The example below shows the <tt>http-conf:destination</tt> element that would
be used to add configuration for an endpoint that was specified by the WSDL fragment <tt>&lt;port
binding="widgetSOAPBinding" name="widgetSOAPPort&gt;</tt> if the endpoint's target
namespace was <tt><a href="http://widgets.widgetvendor.net" class="external-link"
rel="nofollow">http://widgets.widgetvendor.net</a></tt>.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>http-conf:destination Element</b></div><div
class="codeContent panelContent">
<pre class="code-java">

...
  &lt;http-conf:destination name="{http:<span class="code-comment">//widgets/widgetvendor.net}widgetSOAPPort.http-destination&gt;
</span>    ...
  &lt;/http-conf:destination&gt;
...
</pre>
</div></div>

<p>The <tt>http-conf:destination</tt> element has a number of child elements
that specify configuration information. They are described below.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Element</th>
<th class='confluenceTh'>Description</th>
</tr>
<tr>
<td class='confluenceTd'><tt>http-conf:server</tt></td>
<td class='confluenceTd'>Specifies the HTTP connection properties.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>http-conf:contextMatchStrategy</tt></td>
<td class='confluenceTd'>Specifies the parameters that configure the context match strategy
for processing HTTP requests.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>http-conf:fixedParameterOrder</tt></td>
<td class='confluenceTd'>Specifies whether the parameter order of an HTTP request handled
by this destination is fixed.</td>
</tr>
</tbody></table>
</div>


<h3><a name="ServerHTTPTransport-The%7B%7Bserver%7D%7Delement"></a>The <tt>server</tt>
element</h3>

<p>The <tt>http-conf:server</tt>} element is used to configure the properties
of a server's HTTP connection. Its attributes, described below, specify the connection's properties.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Attribute</th>
<th class='confluenceTh'>Description</th>
</tr>
<tr>
<td class='confluenceTd'><tt>ReceiveTimeout</tt></td>
<td class='confluenceTd'>Sets the length of time, in milliseconds, the server tries
to receive a request before the connection times out. The default is 30000. The specify that
the server will not timeout use 0.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>SuppressClientSendErrors</tt></td>
<td class='confluenceTd'>Specifies whether exceptions are to be thrown when an error
is encountered on receiving a request. The default is <tt>false</tt>; exceptions
are thrown on encountering errors.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>SuppressClientReceiveErrors</tt></td>
<td class='confluenceTd'>Specifies whether exceptions are to be thrown when an error
is encountered on sending a response to a client. The default is <tt>false</tt>;
exceptions are thrown on encountering errors.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>HonorKeepAlive</tt></td>
<td class='confluenceTd'>Specifies whether the server honors requests for a connection
to remain open after a response has been sent. The default is <tt>true</tt>; keep-alive
requests are honored.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>RedirectURL</tt></td>
<td class='confluenceTd'>Specifies the URL to which the client request should be redirected
if the URL specified in the client request is no longer appropriate for the requested resource.
In this case, if a status code is not automatically set in the first line of the server response,
the status code is set to 302 and the status description is set to Object Moved. The value
is used as the value of the HTTP <tt>RedirectURL</tt> property.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>CacheControl</tt></td>
<td class='confluenceTd'>Specifies directives about the behavior that must be adhered
to by caches involved in the chain comprising a response from a server to a client.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>ContentLocation</tt></td>
<td class='confluenceTd'>Sets the URL where the resource being sent in a response is
located.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>ContentType</tt></td>
<td class='confluenceTd'>Specifies the media type of the information being sent in a
response. Media types are specified using multipurpose internet mail extensions (MIME) types.
The value is used as the value of the HTTP <tt>ContentType</tt> location.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>ContentEncoding</tt></td>
<td class='confluenceTd'>Specifies any additional content encodings that have been applied
to the information being sent by the service provider. Content encoding labels are regulated
by the Internet Assigned Numbers Authority (IANA). Possible content encoding values include
zip, gzip, compress, deflate, and identity. This value is used as the value of the HTTP <tt>ContentEncoding</tt>
property.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>ServerType</tt></td>
<td class='confluenceTd'>Specifies what type of server is sending the response. Values
take the form program-name/version. For example, Apache/1.2.5.</td>
</tr>
</tbody></table>
</div>


<h3><a name="ServerHTTPTransport-Example"></a>Example</h3>

<p>The example below shows a the configuration for an HTTP service provider endpoint
that honors keep alive requests and suppresses all communication errors.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>HTTP Service Provider Endpoint Configuration</b></div><div
class="codeContent panelContent">
<pre class="code-java">
&lt;beans xmlns=<span class="code-quote">"http:<span class="code-comment">//www.springframework.org/schema/beans"</span>
</span>       xmlns:xsi=<span class="code-quote">"http:<span class="code-comment">//www.w3.org/2001/XMLSchema-instance"</span>
</span>       xmlns:http-conf=<span class="code-quote">"http:<span class="code-comment">//cxf.apache.org/transports/http/configuration"</span>
</span>       xsi:schemaLocation="http:<span class="code-comment">//cxf.apache.org/transports/http/configuration
</span>                             http:<span class="code-comment">//cxf.apache.org/schemas/configuration/http-conf.xsd
</span>                           http:<span class="code-comment">//www.springframework.org/schema/beans
</span>                             http:<span class="code-comment">//www.springframework.org/schema/beans/spring-beans.xsd"&gt;
</span>   
  &lt;http-conf:destination name=<span class="code-quote">"{http:<span class="code-comment">//apache.org/hello_world_soap_http}SoapPort.http-destination"</span>&gt;
</span>    &lt;http-conf:server SuppressClientSendErrors=<span class="code-quote">"<span
class="code-keyword">true</span>"</span>
                      SuppressClientReceiveErrors=<span class="code-quote">"<span
class="code-keyword">true</span>"</span>
                      HonorKeepAlive=<span class="code-quote">"<span class="code-keyword">true</span>"</span>
/&gt;
  &lt;/http-conf:destination&gt;
&lt;/beans&gt;
</pre>
</div></div>

<h2><a name="ServerHTTPTransport-UsingWSDL"></a>Using WSDL</h2>
<h3><a name="ServerHTTPTransport-Namespace"></a>Namespace</h3>

<p>The WSDL extension elements used to configure an HTTP server endpoint are defined
in the namespace <tt><a href="http://cxf.apache.org/transports/http/configuration"
class="external-link" rel="nofollow">http://cxf.apache.org/transports/http/configuration</a></tt>.
It is commonly refered to using the prefix <tt>http-conf</tt>. In order to use
the HTTP configuration elements you will need to add the line shown below to the <tt>definitions</tt>
element of your endpoint's WSDL document.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>HTTP Provider WSDL Element's Namespace</b></div><div
class="codeContent panelContent">
<pre class="code-java">
&lt;definitions ...
       xmlns:http-conf="http:<span class="code-comment">//cxf.apache.org/transports/http/configuration</span>
</pre>
</div></div>

<h3><a name="ServerHTTPTransport-The%7B%7Bserver%7D%7Delement"></a>The <tt>server</tt>
element</h3>

<p>The <tt>http-conf:server</tt> element is used to specify the connection
properties of an HTTP server in a WSDL document. The <tt>http-conf:server</tt>
element is a child of the WSDL port element. It has the same attributes as the <tt>server</tt>
element used in the configuration file.</p>

<h3><a name="ServerHTTPTransport-Example"></a>Example</h3>

<p>The example below shows a WSDL fragment that configures an HTTP server endpoint to
specify that it will not interact with caches.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>WSDL to Configure an HTTP Service Provider Endpoint</b></div><div
class="codeContent panelContent">
<pre class="code-java">
&lt;service ...&gt;
  &lt;port ...&gt;
    &lt;soap:address ... /&gt;
    &lt;http-conf:server CacheControl=<span class="code-quote">"no-cache"</span>
/&gt;
  &lt;/port&gt;
&lt;/service&gt;
</pre>
</div></div>

<h2><a name="ServerHTTPTransport-ServerCacheControlDirectives"></a>Server
Cache Control Directives</h2>

<p>The table below lists the cache control directives supported by an HTTP server.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Directive</th>
<th class='confluenceTh'>Behavior</th>
</tr>
<tr>
<td class='confluenceTd'><tt>no-cache</tt></td>
<td class='confluenceTd'>Caches cannot use a particular response to satisfy subsequent
requests without first revalidating that response with the server. If specific response header
fields are specified with this value, the restriction applies only to those header fields
within the response. If no response header fields are specified, the restriction applies to
the entire response.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>public</tt></td>
<td class='confluenceTd'>Any cache can store the response.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>private</tt></td>
<td class='confluenceTd'>Public (shared) caches cannot store the response because the
response is intended for a single user. If specific response header fields are specified with
this value, the restriction applies only to those header fields within the response. If no
response header fields are specified, the restriction applies to the entire response.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>no-store</tt></td>
<td class='confluenceTd'>Caches must not store any part of response or any part of the
request that invoked it.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>no-transform</tt></td>
<td class='confluenceTd'>Caches must not modify the media type or location of the content
in a response between a server and a client.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>must-revalidate</tt></td>
<td class='confluenceTd'>Caches must revaildate expired entries that relate to a response
before that entry can be used in a subsequent response.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>proxy-revalidate</tt></td>
<td class='confluenceTd'>Means the same as must-revalidate, except that it can only
be enforced on shared caches and is ignored by private unshared caches. If using this directive,
the public cache directive must also be used.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>max-age</tt></td>
<td class='confluenceTd'>Clients can accept a response whose age is no greater that
the specified number of seconds.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>s-max-age</tt></td>
<td class='confluenceTd'>Means the same as max-age, except that it can only be enforced
on shared caches and is ignored by private unshared caches. The age specified by s-max-age
overrides the age specified by max-age. If using this directive, the proxy-revalidate directive
must also be used.</td>
</tr>
<tr>
<td class='confluenceTd'><tt>cache-extension</tt></td>
<td class='confluenceTd'>Specifies additional extensions to the other cache directives.
Extensions might be informational or behavioral. An extended directive is specified in the
context of a standard directive, so that applications not understanding the extended directive
can at least adhere to the behavior mandated by the standard directive.</td>
</tr>
</tbody></table>
</div>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Server+HTTP+Transport">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=60558&revisedVersion=7&originalVersion=6">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Server+HTTP+Transport?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message