blob: 0aae1abd30c2980a786e09b550f5694819aaa59b [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Apache Wink : JAX-RS HTTP Headers</title>
<link rel="stylesheet" href="styles/site.css" type="text/css" />
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
<tr>
<td valign="top" class="pagebody">
<div class="pageheader">
<span class="pagetitle">
Apache Wink : JAX-RS HTTP Headers
</span>
</div>
<div class="pagesubheading">
This page last changed on Sep 22, 2009 by <font color="#0050B2">michael</font>.
</div>
<h1><a name="JAX-RSHTTPHeaders-HTTPHeaders"></a>HTTP Headers</h1>
<p><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">HTTP headers</a> generally store metadata and control information. There are some common headers shared in requests and responses but there are a few specific headers to either a request or a response. Developers should read the HTTP specification for a complete understanding of HTTP headers. Some of the more common HTTP headers are mentioned below in cases where JAX-RS provides convenient methods for the header.</p>
<p>Generally, in order to get the request header name and values, developers can use either an injected @HeaderParam annotated with a parameter/field/property or an injected @Context HttpHeaders parameter/field/property.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">@Path(<span class="code-quote">"/example"</span>)
<span class="code-keyword">public</span> ExampleResource {
@Context HttpHeaders requestHeaders;
@GET
<span class="code-keyword">public</span> void getSomething(@HeaderParam(<span class="code-quote">"User-Agent"</span>) <span class="code-object">String</span> theUserAgent) {
/* use theUserAgent variable or requestHeader's methods to get more info */
}
}
</pre>
</div></div>
<p>In order to set response headers, developers can set them on a javax.ws.rs.core.Response return object.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">@Path(<span class="code-quote">"/example"</span>)
<span class="code-keyword">public</span> ExampleResource {
@GET
<span class="code-keyword">public</span> Response getSomething() {
<span class="code-keyword">return</span> Response.ok(/* some entity */).header(<span class="code-quote">"CustomHeader"</span>, <span class="code-quote">"CustomValue"</span>).build();
}
}
</pre>
</div></div>
<p>A response headers can be set when a MessageBodyWriter#writeTo() method is called.</p>
<p><a name="JAX-RSHTTPHeaders-CommonHeaders"></a></p>
<h3><a name="JAX-RSHTTPHeaders-CommonHeaders"></a>Common Headers</h3>
<p>The common header specifies the size and type of a header. Every header must begin with the common header. The common header must not appear by itself.</p>
<h5><a name="JAX-RSHTTPHeaders-ContentType"></a>Content-Type</h5>
<p>The Content-Type signals the media type of the request/response entity. The Content-Type header on requests is read via HttpHeaders#getMediaType() method. The Content-Type is set for responses when doing a javax.ws.rs.core.Response.ResponseBuilder#type() method or a javax.ws.rs.core.Response.ResponseBuilder#variant() method.</p>
<h5><a name="JAX-RSHTTPHeaders-ContentLanguage"></a>Content-Language</h5>
<p>The Content-Language denotes what language the entity is in. In order to receive the request entity language, use the HttpHeaders#getLanguage() method. In order to set the response entity language, use the javax.ws.rs.core.Response.ResponseBuilder#language() method.</p>
<h5><a name="JAX-RSHTTPHeaders-ContentLength"></a>Content-Length</h5>
<p>The Content-Length is useful for determining the entity's length. If possible, the MessageBodyWriter entity providers will automatically set the Content-Length if possible, and some containers will set the response Content-Length if the entity is small.</p>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Reference</b><br />Refer to the HTTP spec for more details on when this header is set and valid.</td></tr></table></div>
<p><a name="JAX-RSHTTPHeaders-RequestHeaders"></a></p>
<h3><a name="JAX-RSHTTPHeaders-CommonRequestHTTPHeaders"></a>Common Request HTTP Headers</h3>
<p>An HTTP Request Header is a line of text that a client software (i.e. Web Browser) sends to a server together with other request data.</p>
<h5><a name="JAX-RSHTTPHeaders-Accept"></a>Accept</h5>
<p>The Accept header is used to determine the possible response representations that the client prefers such as XML over JSON but not plain text. When a resource method is effectively annotated with a @Produces, any incoming request must have a compatible Accept header value for the resource method to be selected. Clients can set quality parameters (priority ordering) for the best possible response and services generally try to honor the request. To get the best representation of a response, use either the HttpHeaders#getAcceptableMediaTypes() or Request#selectVariant() methods.</p>
<h5><a name="JAX-RSHTTPHeaders-AcceptLanguage"></a>Accept-Language</h5>
<p>Like the Accept header, Accept-Language lists the preferred languages. A&nbsp; HttpHeaders#getAcceptableLanguages() method will list the acceptable languages in a preferred order.</p>
<h5><a name="JAX-RSHTTPHeaders-IfMatchandIfNoneMatch"></a>If-Match and If-None-Match</h5>
<p>If a previous response had an ETag header, the client can re-use the ETag value with the If-Match or If-None-Match request header to do conditional requests (if the server application supported the If-Match/If-None-Match headers). For example, a POST with an If-Match header and an old ETag value should only execute the POST request if the old ETag value is still valid. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Match and If-None-Match headers.</p>
<h5><a name="JAX-RSHTTPHeaders-IfModifiedSinceandIfUnmodifiedSince"></a>If-Modified-Since and If-Unmodified-Since</h5>
<p>Like ETags, If-Modified-Since and If-Unmodified-Since are based on the Last-Modified date. Using either request header with a date, will set up a conditional request (if the server application supports the headers). For instance, a GET with an If-Modified-Since header of an old known date would allow the server to send back a response with just a HTTP status code of 304 (Not Modified). By sending back a HTTP status code of 304, the server is telling the client that the resource has not changed so there is no need to re-download the resource representation. This could save precious bandwidth for the client. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Modified-Since and If-Unmodified-Since headers.</p>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Important Note</b><br />Note that date formats are specified in the HTTP specification.</td></tr></table></div>
<p><a name="JAX-RSHTTPHeaders-ResponseHeaders"></a></p>
<h3><a name="JAX-RSHTTPHeaders-CommonResponseHTTPHeaders"></a>Common Response HTTP Headers</h3>
<p>HTTP Headers form the core of an HTTP request, and are very important in an HTTP response. They define various characteristics of the data that is requested or the data that has been provided. The headers are separated from the request or response body by a blank line</p>
<h5><a name="JAX-RSHTTPHeaders-ETag"></a>ETag</h5>
<p>ETags or entity tags can be set. Like a hashcode, it is given to the client so a client can use various control request headers such as If-Match and If-None-Match for conditional requests. javax.ws.rs.core.Response.ResponseBuilder#tag() and javax.ws.rs.core.EntityTag are useful for ETags.</p>
<h5><a name="JAX-RSHTTPHeaders-Expires"></a>Expires</h5>
<p>The Expires response header indicates the amount of time that the response entity should be cached. It is useful to set the expiration for data that is not going to change for a known time length. Browsers use this response header to manage their caches among other user agents.The javax.ws.rs.core.Response.ResponseBuilder#expires() method can be used to set the Expires header.</p>
<h5><a name="JAX-RSHTTPHeaders-LastModified"></a>Last-Modified</h5>
<p>Last-Modified specifies the date when the resource was changed. A client can use the response value in combination with If-Modified-Since and If-Unmodified-Since request headers to perform conditional requests.The javax.ws.rs.core.Response.ResponseBuilder#lastModified() method can be used to set the Last-Modified header.</p>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Important Note</b><br />Note that date formats are specified in the HTTP specification.</td></tr></table></div>
<h5><a name="JAX-RSHTTPHeaders-Location"></a>Location</h5>
<p>The Location response header usually indicates where the resource is located (in a redirect) or the URI of the new resource (when resources are created and usually in a HTTP 201 response). The javax.ws.rs.core.Response.ResponseBuilder#location()method can be used to set the Location header.</p>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td height="12" background="http://cwiki.apache.org/confluence/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
</tr>
<tr>
<td align="center"><font color="grey">Document generated by Confluence on Nov 11, 2009 06:57</font></td>
</tr>
</table>
</body>
</html>