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