| <!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 Parameters</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 Parameters |
| </span> |
| </div> |
| <div class="pagesubheading"> |
| This page last changed on Sep 22, 2009 by <font color="#0050B2">michael</font>. |
| </div> |
| |
| <h1><a name="JAX-RSParameters-Parameters"></a>Parameters</h1> |
| |
| <p>Parameters are used to pass and add additional information to a request. Search queries, offsets/pages in a collection, and other information can be used. While parameters are sometimes used to add more verbs to HTTP, it is advised not to use parameters as a way to create new HTTP methods or to make existing HTTP methods break the generally understood attributes (i.e. idempotent).</p> |
| |
| <p>Parameters can be any basic Java primitive type including java.lang.String as well as types with a constructor that takes in a single String or a valueOf(String) static method.In addition, List, SortedSet, and Set can be used where the generic type is one of the previously mentioned types such as a <b>Set<String></b> when a parameter can have multiple values.</p> |
| |
| <p>When full control is needed for parsing requests, it is generally recommend that developers use a String as the parameter type so that some basic inspection can be performed and developers can customize error path responses.</p> |
| |
| <p><a name="JAX-RSParameters-QueryParameter"></a></p> |
| |
| <h3><a name="JAX-RSParameters-QueryParameters%28@QueryParam%29"></a>Query Parameters (@QueryParam)</h3> |
| |
| <p>Query parameters are one of the better known parameters. A query string is appended to the request URL with a leading "?" and then name/value pairs.</p> |
| |
| <div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Query Parameter Examples</b><br />Refer to the following links:<br/> |
| <a href="http://www.google.com/search?q=apache+wink">http://www.google.com/search?q=apache+wink</a><br/> |
| <a href="http://www.example.com/users?offset=100&numPerPage=20">http://www.example.com/users?offset=100&numPerPage=20</a> </td></tr></table></div> |
| |
| <p>In order to enable JAX-RS to read a query parameters, add a parameter to the resource method and annotate with <b>@QueryParam</b>:</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> class RootResource { |
| @GET |
| <span class="code-keyword">public</span> Response invokeWithParameters(@QueryParam(<span class="code-quote">"q"</span>) <span class="code-object">String</span> searchTerm) { |
| <span class="code-keyword">if</span>(q == <span class="code-keyword">null</span>) { |
| <span class="code-keyword">return</span> Response.status(Status.BAD_REQUEST).build(); |
| } |
| /* <span class="code-keyword">do</span> a search */ |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| } |
| </pre> |
| </div></div> |
| <p>If a HTTP GET request to "/example?q=abcd" is made, searchTerm will have "abcd" as the value when invoked.</p> |
| |
| <p><a name="JAX-RSParameters-PathParameter"></a></p> |
| |
| <h3><a name="JAX-RSParameters-PathParameters%28@PathParam%29"></a>Path Parameters (@PathParam)</h3> |
| |
| <p>Path parameters take the incoming URL and match parts of the path as a parameter. By including <em>{name}</em> in a <b>@Path</b> annotation, the resource can later access the matching part of the URI to a path parameter with the corresponding "<b>name</b>". Path parameters make parts of the request URL as parameters which can be useful in embedding request parameter information to a simple URL.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">@Path(<span class="code-quote">"/books/{bookid}"</span>) |
| <span class="code-keyword">public</span> class BookResource { |
| @GET |
| <span class="code-keyword">public</span> Response invokeWithBookId(@PathParam(<span class="code-quote">"bookid"</span>) <span class="code-object">String</span> bookId) { |
| /* get the info <span class="code-keyword">for</span> bookId */ |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| |
| @GET |
| @Path(<span class="code-quote">"{language}"</span>) |
| <span class="code-keyword">public</span> Response invokeWithBookIdAndLanguage(@PathParam(<span class="code-quote">"bookid"</span>) <span class="code-object">String</span> bookId, @PathParam(<span class="code-quote">"language"</span>) <span class="code-object">String</span> language) { |
| /* get the info <span class="code-keyword">for</span> bookId */ |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| } |
| </pre> |
| </div></div> |
| <p>In the previous example, HTTP GET to /books/1 or to /books/abcd would result in invokeWithBookId being called. If a HTTP GET request is issued to /books/1/en or /books/1/fr or /books/abcd/jp, then invokeWithBookIdAndLanguage would be invoked with the appropriate parameters.</p> |
| |
| <p><a name="JAX-RSParameters-MatrixParameter"></a></p> |
| |
| <h3><a name="JAX-RSParameters-MatrixParameters%28@MatrixParam%29"></a>Matrix Parameters (@MatrixParam)</h3> |
| |
| <p>Matrix parameters are not as widely used on the Internet today. However, you can read a MatrixParam just as easily as any other parameter.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">@Path(<span class="code-quote">"/"</span>) |
| <span class="code-keyword">public</span> class RootResource { |
| @GET |
| <span class="code-keyword">public</span> Response invokeWithParameters(@MatrixParam(<span class="code-quote">"name"</span>) <span class="code-object">String</span> name) { |
| <span class="code-keyword">if</span>(name == <span class="code-keyword">null</span>) { |
| <span class="code-keyword">return</span> Response.status(Status.BAD_REQUEST).build(); |
| } |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| } |
| </pre> |
| </div></div> |
| <p><a name="JAX-RSParameters-HeaderParameter"></a></p> |
| |
| <h3><a name="JAX-RSParameters-HeaderParameters%28@HeaderParam%29"></a>Header Parameters (@HeaderParam)</h3> |
| |
| <p>Header parameters are useful especially when there are additional metadata control parameters that need to be passed in for example, security information, cache information, and so forth.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">@Path(<span class="code-quote">"/"</span>) |
| <span class="code-keyword">public</span> class RootResource { |
| @GET |
| <span class="code-keyword">public</span> Response invokeWithParameters(@HeaderParam(<span class="code-quote">"controlInfo"</span>) <span class="code-object">String</span> controlInfo) { |
| <span class="code-keyword">if</span>(controlInfo == <span class="code-keyword">null</span>) { |
| <span class="code-keyword">return</span> Response.status(Status.BAD_REQUEST).build(); |
| } |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| } |
| </pre> |
| </div></div> |
| |
| <p><a name="JAX-RSParameters-CookieParameter"></a></p> |
| |
| <h3><a name="JAX-RSParameters-CookieParameters%28@CookieParam%29"></a>CookieParameters (@CookieParam)</h3> |
| |
| <p>In a REST application, requests are stateless although applications sometimes use Cookies for various reasons, such as adding some stateless resource viewing information without embedding it into the URL such as the maximum number of items to retrieve. The CookieParam annotation is used to easily retrieve the information.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">@Path(<span class="code-quote">"/"</span>) |
| <span class="code-keyword">public</span> class RootResource { |
| @GET |
| <span class="code-keyword">public</span> Response invokeWithParameters(@CookieParam(<span class="code-quote">"max"</span>) <span class="code-object">String</span> maximumItems) { |
| <span class="code-keyword">if</span>(userId == <span class="code-keyword">null</span>) { |
| <span class="code-keyword">return</span> Response.status(Status.BAD_REQUEST).build(); |
| } |
| <span class="code-keyword">return</span> Response.ok(/* some entity here */).build(); |
| } |
| } |
| </pre> |
| </div></div> |
| |
| |
| </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> |
