content/documentation/1.1.1/html/5.3 Resource Matching.html - wink-website - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
     <head>
         <title>Apache Wink : 5.3 Resource Matching</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.3 Resource Matching
                                                     </span>
 				    </div>
 				    <div class="pagesubheading">
 					    This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
 				    </div>

 				    <h1><a name="5.3ResourceMatching-ResourceMatching"></a>Resource Matching</h1>

 <p>Apache Wink provides a Continued Search mode when searching for a resource method to invoke during request processing, which is an extended search mode to the algorithm defined by the JAX-RS specification.</p>


 <h2><a name="5.3ResourceMatching-ResourceMatchingOverview"></a>Resource Matching Overview</h2>

 <p>Section 3.7.2 of the JAX-RS specification describes the process of matching requests to resource methods. The fact that only the first matching root resource (section 1(f) of the algorithm) and only the first matching sub-resource locator (section 2(g) of the algorithm) are selected during the process makes it difficult for application developers to implement certain scenarios.<br/>
 For example, it is impossible to have two resources anchored to the same URI, each having its own set of supported methods:</p>

 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <pre class="code-xml">@Path(<span class="code-quote">"my/service"</span>)
 public class ResourceA {
     @GET
     @Produces(<span class="code-quote">"text/plain"</span>)
     public String getText() {...}
 }

 @Path(<span class="code-quote">"my/service"</span>)
 public class ResourceB {
     @GET
     @Produces(<span class="code-quote">"text/html"</span>)
     public String getHtml() {...}
 }
 </pre>
 </div></div>

 <h3><a name="5.3ResourceMatching-Explanation"></a>Explanation</h3>

 <p>In order to implement this according to the JAX-RS specification, ResourceB must  extend ResourceA and be registered instead of ResourceA. However, this may not always be possible, such as in an application that uses JAX-RS as the web service frontend while providing an open architecture for registering extending services. For example, Firefox that provides an Extensions mechanism. The extending service must be aware of the core implementation workings and classes, that may not always be plausible. Moreover, it is impossible for a service to extend the functionality of another service without knowing the inner workings of that service, that creates an "evil" dependency between service implementations.</p>

 <p>In order to solve this problem, Apache Wink provides a special resource Continued Search mode when searching for a resource and method to invoke. By default, this mode is off, meaning that the search algorithm is strictly JAX-RS compliant. When this mode is activated, and a root resource or sub-resource locator proves to be a dead-end, the Apache Wink runtime will continue to search from the next root-resource or sub-resource locator, as if they were the first match.</p>

 <p>In the previous example, there is no way to know which of the resources is a first match for a request to "<b>/my/service</b>". If the Continued Search mode is off, either the getText() method is unreachable or the getHtml() method is unreachable. However, when the Continued Search mode is active, a request for text/plain reaches the getText() method in ResourceA, and a request for text/html reaches the getHtml() method in ResourceB.</p>

 <h2><a name="5.3ResourceMatching-Configuration"></a>Configuration</h2>

 <p>The Continued Search mode is activated by setting the value of the wink.searchPolicyContinuedSearch key in the application configuration properties file to true.<br/>
 If the key is set to anything else but true or if it does not exist in the properties file, then the Continued Search mode is set to off, and the behavior is strictly JAX-RS compliant.</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>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<title>Apache Wink : 5.3 Resource Matching</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.3 Resource Matching
	</span>
	</div>
	<div class="pagesubheading">
	This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
	</div>

	<h1><a name="5.3ResourceMatching-ResourceMatching"></a>Resource Matching</h1>

	<p>Apache Wink provides a Continued Search mode when searching for a resource method to invoke during request processing, which is an extended search mode to the algorithm defined by the JAX-RS specification.</p>


	<h2><a name="5.3ResourceMatching-ResourceMatchingOverview"></a>Resource Matching Overview</h2>

	<p>Section 3.7.2 of the JAX-RS specification describes the process of matching requests to resource methods. The fact that only the first matching root resource (section 1(f) of the algorithm) and only the first matching sub-resource locator (section 2(g) of the algorithm) are selected during the process makes it difficult for application developers to implement certain scenarios.<br/>
	For example, it is impossible to have two resources anchored to the same URI, each having its own set of supported methods:</p>

	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
	<pre class="code-xml">@Path(<span class="code-quote">"my/service"</span>)
	public class ResourceA {
	@GET
	@Produces(<span class="code-quote">"text/plain"</span>)
	public String getText() {...}
	}

	@Path(<span class="code-quote">"my/service"</span>)
	public class ResourceB {
	@GET
	@Produces(<span class="code-quote">"text/html"</span>)
	public String getHtml() {...}
	}
	</pre>
	</div></div>

	<h3><a name="5.3ResourceMatching-Explanation"></a>Explanation</h3>

	<p>In order to implement this according to the JAX-RS specification, ResourceB must extend ResourceA and be registered instead of ResourceA. However, this may not always be possible, such as in an application that uses JAX-RS as the web service frontend while providing an open architecture for registering extending services. For example, Firefox that provides an Extensions mechanism. The extending service must be aware of the core implementation workings and classes, that may not always be plausible. Moreover, it is impossible for a service to extend the functionality of another service without knowing the inner workings of that service, that creates an "evil" dependency between service implementations.</p>

	<p>In order to solve this problem, Apache Wink provides a special resource Continued Search mode when searching for a resource and method to invoke. By default, this mode is off, meaning that the search algorithm is strictly JAX-RS compliant. When this mode is activated, and a root resource or sub-resource locator proves to be a dead-end, the Apache Wink runtime will continue to search from the next root-resource or sub-resource locator, as if they were the first match.</p>

	<p>In the previous example, there is no way to know which of the resources is a first match for a request to "<b>/my/service</b>". If the Continued Search mode is off, either the getText() method is unreachable or the getHtml() method is unreachable. However, when the Continued Search mode is active, a request for text/plain reaches the getText() method in ResourceA, and a request for text/html reaches the getHtml() method in ResourceB.</p>

	<h2><a name="5.3ResourceMatching-Configuration"></a>Configuration</h2>

	<p>The Continued Search mode is activated by setting the value of the wink.searchPolicyContinuedSearch key in the application configuration properties file to true.<br/>
	If the key is set to anything else but true or if it does not exist in the properties file, then the Continued Search mode is set to off, and the behavior is strictly JAX-RS compliant.</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>