| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>Apache Wink : 5.2 Annotations</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 : 5.2 Annotations |
| </span> |
| </div> |
| <div class="pagesubheading"> |
| This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>. |
| </div> |
| |
| <h1><a name="5.2Annotations-Annotations"></a>Annotations</h1> |
| |
| <p>Apache Wink provides several annotations in addition to those defined by the JAX-RS specification. The following section describes these annotations in detail.</p> |
| |
| |
| <h2><a name="5.2Annotations-@WorkspaceAnnotation"></a>@Workspace Annotation</h2> |
| |
| <p>The purpose of the @Workspace annotation is to associate a "Collection Resource" with a workspace element and collection elements in an APP Service Document.</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 />For more information regarding the APP Service Document, refer to section <a href="5.4 APP Service Document.html" title="5.4 APP Service Document">5.4 APP Service Document</a></td></tr></table></div> |
| <p>The workspaceTitle annotation parameter specifies the title of the workspace and the collectionTitle annotation parameter specifies the title of the collection.</p> |
| |
| <h3><a name="5.2Annotations-@WorkspaceAnnotationSpecification"></a>@Workspace Annotation Specification</h3> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Value </th> |
| <th class='confluenceTh'> Description </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Mandatory</b> </td> |
| <td class='confluenceTd'> No </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Target</b> </td> |
| <td class='confluenceTd'> Resource class </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Parameters</b> </td> |
| <td class='confluenceTd'> <b>Name</b> </td> |
| <td class='confluenceTd'> <b>Type</b> <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> </td> |
| <td class='confluenceTd'> workspaceTitle <br clear="all" /> </td> |
| <td class='confluenceTd'> String <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> </td> |
| <td class='confluenceTd'> collectionTitle <br clear="all" /> </td> |
| <td class='confluenceTd'> String <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Example</b> </td> |
| <td class='confluenceTd'> @Workspace(workspaceTitle = "Title", <br clear="all" /> |
| collectionTitle = "Collection") x <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h3><a name="5.2Annotations-@WorkspaceAnnotationExample"></a>@Workspace Annotation Example</h3> |
| |
| <p>The following example demonstrates the use of @Workspace annotation on two resources in order to have the auto-generated APP service document contain the information about them.</p> |
| |
| <p>Given the following collection Resources definitions, ResourceA and ResourceB, the result is displayed in the "Auto Generated APP Service Document" table that follows.</p> |
| |
| <h4><a name="5.2Annotations-ResourceADefinition"></a>ResourceA Definition</h4> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Workspace(workspaceTitle = <span class="code-quote">"Services"</span>, collectionTitle = <span class="code-quote">"Service1"</span>) |
| @Path(<span class="code-quote">"services/service1"</span>) |
| public class ResourceA { |
| @POST |
| @Produces(<span class="code-quote">"text/plain"</span>) |
| @Consumes({<span class="code-quote">"application/atom+xml"</span>, <span class="code-quote">"application/xml"</span>}) |
| public String getText() {return <span class="code-quote">"hey there1"</span>;} |
| } |
| </pre> |
| </div></div> |
| |
| <h4><a name="5.2Annotations-ResourceBDefinition"></a>ResourceB Definition</h4> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Workspace(workspaceTitle = <span class="code-quote">"Services"</span>, collectionTitle = <span class="code-quote">"Service2"</span>) |
| @Path(<span class="code-quote">"services/service2"</span>) |
| public class ResourceB { |
| @POST |
| @Produces(<span class="code-quote">"text/plain"</span>) |
| @Consumes({<span class="code-quote">"application/atom+xml"</span>, <span class="code-quote">"application/xml"</span>}) |
| public String getText() {return <span class="code-quote">"hey there2"</span>;} |
| } |
| </pre> |
| </div></div> |
| <p>The auto-generated APP Service Document is as follows:</p> |
| |
| <h4><a name="5.2Annotations-AutoGeneratedAPPServiceDocument"></a>Auto Generated APP Service Document</h4> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml"><service <span class="code-keyword">xmlns:atom</span>=http://www.w3.org/2005/Atom |
| xmlns=<span class="code-quote">"http://www.w3.org/2007/app"</span>> |
| <span class="code-tag"><workspace></span> |
| <span class="code-tag"><atom:title></span>Services<span class="code-tag"></atom:title></span> |
| <span class="code-tag"><collection href=<span class="code-quote">"services/service1"</span>></span> |
| <span class="code-tag"><atom:title></span>Service1<span class="code-tag"></atom:title></span> |
| <span class="code-tag"><accept></span>application/xml<span class="code-tag"></accept></span> |
| <span class="code-tag"><accept></span>application/atom+xml<span class="code-tag"></accept></span> |
| <span class="code-tag"></collection></span> |
| <span class="code-tag"><collection href=<span class="code-quote">"services/service2"</span>></span> |
| <span class="code-tag"><atom:title></span>Service2<span class="code-tag"></atom:title></span> |
| <span class="code-tag"><accept></span>application/xml<span class="code-tag"></accept></span> |
| <span class="code-tag"><accept></span>application/atom+xml<span class="code-tag"></accept></span> |
| <span class="code-tag"></collection></span> |
| <span class="code-tag"></workspace></span> |
| <span class="code-tag"></service></span> |
| </pre> |
| </div></div> |
| |
| <h2><a name="5.2Annotations-@AssetAnnotation"></a>@Asset Annotation</h2> |
| |
| <p>The @Asset annotation is a marker annotation used by the Apache Wink runtime in order to identify an entity as an Asset.</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 />For more information about Assets refer to section <a href="5.9 Assets.html" title="5.9 Assets">5.9 Assets</a>.</td></tr></table></div> |
| |
| <h3><a name="5.2Annotations-@AssetAnnotationSpecification"></a>@Asset Annotation Specification</h3> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Value <br clear="all" /> </th> |
| <th class='confluenceTh'> Description <br clear="all" /> </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> Mandatory <br clear="all" /> </td> |
| <td class='confluenceTd'> No <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> Target <br clear="all" /> </td> |
| <td class='confluenceTd'> Resource class <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> Parameters <br clear="all" /> </td> |
| <td class='confluenceTd'> None <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> Example <br clear="all" /> </td> |
| <td class='confluenceTd'> @Asset <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h2><a name="5.2Annotations-@ScopeAnnotation"></a>@Scope Annotation</h2> |
| |
| <p>The JAX-RS specification defines the default lifecycle behavior for resources and providers, and the option for controlling the lifecycle through the javax.ws.rs.core.Application class.</p> |
| |
| <p>Apache Wink provides the @Scope annotation to specify the lifecycle of a provider or resource.</p> |
| |
| <h3><a name="5.2Annotations-@ScopeAnnotationSpecification"></a>@Scope Annotation Specification</h3> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Value </th> |
| <th class='confluenceTh'> Description </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Mandatory</b> </td> |
| <td class='confluenceTd'> No </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Target</b> </td> |
| <td class='confluenceTd'> Provider class or Resource class </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Parameters</b> </td> |
| <td class='confluenceTd'> <b>Name</b> </td> |
| <td class='confluenceTd'> <b>Type</b> <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> </td> |
| <td class='confluenceTd'> Value <br clear="all" /> </td> |
| <td class='confluenceTd'> ScopeType enum <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Example</b> </td> |
| <td class='confluenceTd'> @Scope(ScopeType.PROTOTYPE) <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h3><a name="5.2Annotations-ResourceExample"></a>Resource Example</h3> |
| |
| <p>The following example illustrates how to define a resource with a singleton lifecycle.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Scope(ScopeType.SINGLETON) |
| @Path(<span class="code-quote">"service1"</span>) |
| public class ResourceA { |
| ... |
| } |
| </pre> |
| </div></div> |
| |
| <h3><a name="5.2Annotations-ProviderExample"></a>Provider Example</h3> |
| |
| <p>The following example illustrates how to define a provider with a prototype lifecycle.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Scope(ScopeType.PROTOTYPE) |
| @Provider |
| public class EntityProvider implements MessageBodyReader<span class="code-tag"><String></span> { |
| ... |
| } |
| </pre> |
| </div></div> |
| |
| <h2><a name="5.2Annotations-@ParentAnnotation"></a>@Parent Annotation</h2> |
| |
| <p>The @Parent annotation provides the ability to define a base template URI for the URI specified in a resources @Path annotation.<br/> |
| If a resource is annotated with the @Parent annotation, the Apache Wink runtime calculates the final resource template by first retrieving the value of the @Parent annotation, which holds the parent resource class, and then concatenates the resource path template definition to the path template definition of the parent resource.</p> |
| |
| <h3><a name="5.2Annotations-@ParentAnnotationSpecification"></a>@Parent Annotation Specification</h3> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Value </th> |
| <th class='confluenceTh'> Description </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Mandatory</b> </td> |
| <td class='confluenceTd'> No </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Target</b> </td> |
| <td class='confluenceTd'> Provider class or Resource class </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Parameters</b> </td> |
| <td class='confluenceTd'> <b>Name</b> </td> |
| <td class='confluenceTd'> <b>Type</b> <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> </td> |
| <td class='confluenceTd'> Value <br clear="all" /> </td> |
| <td class='confluenceTd'> Class<?> <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> <b>Example</b> </td> |
| <td class='confluenceTd'> @Parent(ParentResource.class) <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h4><a name="5.2Annotations-Example1"></a>Example 1</h4> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Path(<span class="code-quote">"services"</span>) |
| public class ParentResource { |
| ... |
| } |
| </pre> |
| </div></div> |
| |
| <h4><a name="5.2Annotations-Example2"></a>Example 2</h4> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">@Parent(BaseResource.class) |
| @Path(<span class="code-quote">"service1"</span>) |
| public class ResourceA { |
| ... |
| } |
| </pre> |
| </div></div> |
| |
| <h5><a name="5.2Annotations-Explanation"></a>Explanation</h5> |
| |
| <p>In the example, the user defined two resources: A ParentResource and ResourceA. ParentResource defines the @Path annotation to associate it with "<b>services</b>" URI. ResourceA defines the @Path annotation to associate it with "<b>service1</b>" URI and defines ParentResource to be its parent by specifying it in the @Parent annotation. In this case, the final URI path for ResourceA is "<b>services/service1</b>".</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> |
