blob: 25fbb51718bde9ed12f127b1b19fcdc9b30cc13b [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 : 5.7 Handler Chain - Runtime Extension</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.7 Handler Chain - Runtime Extension
</span>
</div>
<div class="pagesubheading">
This page last changed on Oct 12, 2009 by <font color="#0050B2">bluk</font>.
</div>
<h1><a name="5.7HandlerChain-RuntimeExtension-HandlerChainRuntimeExtension"></a>Handler Chain - Runtime Extension</h1>
<p>The Apache Wink runtime utilizes three Handler Chains for the complete processing of a request: Request chain, Response chain and Error chain. A handler receives a MessageContext instance for accessing and manipulating the current request information and a HandlerChain instance for advancing the chain. It is the responsibility of the handler to pass control to the next handler on the chain by invoking the doChain() method on the HandlerChain instance.</p>
<p>A handler may call the doChain() method several times if needed, so handlers are required to consider the possibility they will be invoked more than once for the same request.<br/>
All handler related interfaces reside in the org.apache.wink.server.handlers package.</p>
<p>The implementation of separate chains provides the ability to move up and down one chain before moving on to the next chain. This is particularly useful for the implementation of the JAX-RS resource-method search algorithm that includes invoking sub-resource locators, and implementing the Continued Search mode.</p>
<h2><a name="5.7HandlerChain-RuntimeExtension-Handlers"></a>Handlers</h2>
<p>There are two types of handlers:</p>
<ul>
<li><b>System Handler -</b> are the handlers that implement the core engine of the Apache Wink runtime. The Apache Wink runtime will not function correctly if any of the system handlers are removed from the chain.</li>
</ul>
<ul>
<li><b>User Handler -</b> are the handlers that are provided by an application to customize a chains behavior and to add unique functionality to it. User handlers are not part of the core functionality of Apache Wink.</li>
</ul>
<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 />In order to customize a handler chain refer to section 2 "<b>Apache Wink Building Blocks</b>", <a href="2 Apache Wink Building Blocks.html#2ApacheWinkBuildingBlocks-CustomizationoftheHandlersChain">Customization of the Handlers Chain</a></td></tr></table></div>
<h2><a name="5.7HandlerChain-RuntimeExtension-MessageContext"></a>Message Context</h2>
<p>The MessageContext allows the following:<br/>
Allows handlers to access and manipulate the current request informationAllows handlers to maintain a state by setting attributes on the message context, as the handlers themselves are singletons and therefore statelessAllows handlers to pass information to other handlers on the chain</p>
<h2><a name="5.7HandlerChain-RuntimeExtension-RequestHandlerChain"></a>Request Handler Chain</h2>
<p>The Request Handler Chain is responsible for processing a request according to the JAX-RS specification by accepting the request, searching for the resource method to invoke, de-serializing the request entity and finally for invoking the resource method. It is responsible for invoking sub-resource locators by moving up and down the chain as needed. A Request handler is a class that implements the org.apache.wink.server.handlers.RequestHandler interface.</p>
<h2><a name="5.7HandlerChain-RuntimeExtension-SystemRequestHandlers"></a>System Request Handlers</h2>
<p>The following is a list of system handlers comprising the request handler chain in the order that they appear in the chain.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Handler </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> SearchResultHandler </td>
<td class='confluenceTd'> Responsible for throwing the search result error if there was one during the search for the resource method </td>
</tr>
<tr>
<td class='confluenceTd'> OptionsMethodHandler </td>
<td class='confluenceTd'> Generates a response for an OPTIONS request in case that there is no resource method that is associated with OPTIONS, according to the JAX-RS spec </td>
</tr>
<tr>
<td class='confluenceTd'> HeadMethodHandler </td>
<td class='confluenceTd'> Handles a response for a HEAD request in case that there is no resource method that is associated with HEAD, according to the JAX-RS spec </td>
</tr>
<tr>
<td class='confluenceTd'> FindRootResourceHandler </td>
<td class='confluenceTd'> Locates the root resource that best matches the request </td>
</tr>
<tr>
<td class='confluenceTd'> FindResourceMethodHandler </td>
<td class='confluenceTd'> Locates the actual method to invoke that matches the request, invoking sub-resource locators as needed </td>
</tr>
<tr>
<td class='confluenceTd'> CreateInvocationParametersHandler </td>
<td class='confluenceTd'> Creates the parameters of the resource method to invoke and de-serializes the request entity using the appropriate MessageBodyReader </td>
</tr>
<tr>
<td class='confluenceTd'> InvokeMethodHandler </td>
<td class='confluenceTd'> Invokes the resource method </td>
</tr>
</tbody></table>
<h3><a name="5.7HandlerChain-RuntimeExtension-UserRequestHandlers"></a>User Request Handlers</h3>
<p>User request handlers are inserted before the InvokeMethodHandler handler.</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 />In order to customize a handler chain refer to section 2 "<b>Apache Wink Building Blocks</b>", <a href="2 Apache Wink Building Blocks.html#2ApacheWinkBuildingBlocks-CustomizationoftheHandlersChain">Customization of the Handlers Chain</a></td></tr></table></div>
<h2><a name="5.7HandlerChain-RuntimeExtension-ResponseHandlerChain"></a>Response Handler Chain</h2>
<p>The Response Handler Chain is responsible for handling the object returned from invoking a resource method or sub-resource method according to the JAX-RS specification. It is responsible for determining the response status code, selecting the response media type and for serializing the response entity.<br/>
A Response handler is a class that implements the <b>org.apache.wink.server.handlers.ResponseHandler interface.</b></p>
<h3><a name="5.7HandlerChain-RuntimeExtension-SystemResponseHandlers"></a>System Response Handlers</h3>
<p>The following is a list of system handlers comprising the response handler chain in the order that they appear in the chain.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Handler <br clear="all" /> </th>
<th class='confluenceTh'> Description <br clear="all" /> </th>
</tr>
<tr>
<td class='confluenceTd'> PopulateResponseStatusHandler <br clear="all" /> </td>
<td class='confluenceTd'> Determines the response status code, according to the JAX-RS spec <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> PopulateResponseMediaTypeHandler <br clear="all" /> </td>
<td class='confluenceTd'> Determines the response media type, according to the JAX-RS spec <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> FlushResultHandler <br clear="all" /> </td>
<td class='confluenceTd'> Serializes the response entity using the appropriate MessageBodyWriter <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> HeadMethodHandler <br clear="all" /> </td>
<td class='confluenceTd'> Performs cleanup operations in case that there was no resource method that was associated with HEAD. <br clear="all" /> </td>
</tr>
</tbody></table>
<h3><a name="5.7HandlerChain-RuntimeExtension-UserResponseHandlers"></a>User Response Handlers</h3>
<p>User response handlers are inserted before the FlushResultHandler handler. Apache Wink initializes the user response handler chain with the <b>CheckLocationHeaderHandler</b> handler that verifies that the "<b>Location</b>" response header is present on a response when there is a status code that requires it, for example, status code: 201.</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 />In order to customize a handler chain refer to section 2 "<b>Apache Wink Building Blocks</b>", <a href="2 Apache Wink Building Blocks.html#2ApacheWinkBuildingBlocks-CustomizationoftheHandlersChain">Customization of the Handlers Chain</a></td></tr></table></div>
<h2><a name="5.7HandlerChain-RuntimeExtension-ErrorHandlerChain"></a>Error Handler Chain</h2>
<p>The Error Handler Chain is responsible for handling all of the exceptions that are thrown during the invocation of the Request and Response handler chains, according to the JAX-RS specification for handling exceptions. It is responsible for determining the response status code, selecting the response media type and for serializing the response entity.</p>
<p>An Error handler is a class that implements the org.apache.wink.server.handlers.ResponseHandler interface.</p>
<h3><a name="5.7HandlerChain-RuntimeExtension-SystemErrorHandlers"></a>System Error Handlers</h3>
<p>The following is a list of system handlers comprising the error handler chain in the order that they appear in the chain.</p>
<h3><a name="5.7HandlerChain-RuntimeExtension-ErrorHandlers"></a>Error Handlers</h3>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Handler <br clear="all" /> </th>
<th class='confluenceTh'> Description <br clear="all" /> </th>
</tr>
<tr>
<td class='confluenceTd'> PopulateErrorResponseHandler <br clear="all" /> </td>
<td class='confluenceTd'> Prepares the response entity from a thrown exception according to the JAX-RS specification <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> PopulateResponseStatusHandler <br clear="all" /> </td>
<td class='confluenceTd'> Determines the response status code according to the JAX-RS spec <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> PopulateResponseMediaTypeHandler <br clear="all" /> </td>
<td class='confluenceTd'> Determines the response media type, according to the JAX-RS spec <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> FlushResultHandler <br clear="all" /> </td>
<td class='confluenceTd'> Serializes the response entity using the appropriate MessageBodyWriter <br clear="all" /> </td>
</tr>
</tbody></table>
<h3><a name="5.7HandlerChain-RuntimeExtension-UserErrorHandlers"></a>User Error Handlers</h3>
<p>User error handlers are inserted before the FlushResultHandler handler.</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 />In order to customize a handler chain refer to section 2 "<b>Apache Wink Building Blocks</b>", <a href="2 Apache Wink Building Blocks.html#2ApacheWinkBuildingBlocks-CustomizationoftheHandlersChain">Customization of the Handlers Chain</a></td></tr></table></div>
<h2><a name="5.7HandlerChain-RuntimeExtension-RequestProcessing"></a>Request Processing</h2>
<p>The following details how the Apache Wink runtime performs request processing:</p>
<ol>
<li>Create new instances of the three handler chains. The handlers themselves are singletons.</li>
<li>Create a new instance of a MessageContext to pass between the handlers.</li>
<li>Invoke the first handler on the Request chain.</li>
<li>Once the request chain is complete, invoke the Response chain and pass it the MessageContext that was used in the Request chain.</li>
<li>Make both chains and the MessageContext available for garbage collection.</li>
</ol>
<p>If at any time during the execution of a Request or Response chain an exception is thrown, catch the exception, wrap it in a new MessageContext instance and invoke the Error chain to produce an appropriate response.</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>