You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wink.apache.org by el...@apache.org on 2009/11/11 08:39:50 UTC
svn commit: r834791 [3/8] - in /incubator/wink/site/trunk/src/site: apt/
resources/1.0/html/ resources/1.0/html/attachments/
resources/1.0/html/attachments/2328628/
resources/1.0/html/attachments/2328642/
resources/1.0/html/attachments/2329360/ resourc...
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/5.7 Handler Chain - Runtime Extension.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/5.7%20Handler%20Chain%20-%20Runtime%20Extension.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/5.7 Handler Chain - Runtime Extension.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/5.7 Handler Chain - Runtime Extension.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,208 @@
+<!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>
\ No newline at end of file
Propchange: incubator/wink/site/trunk/src/site/resources/1.0/html/5.7 Handler Chain - Runtime Extension.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/5.8 Link Builder.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/5.8%20Link%20Builder.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/5.8 Link Builder.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/5.8 Link Builder.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,124 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 5.8 Link Builder</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.8 Link Builder
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 12, 2009 by <font color="#0050B2">bluk</font>.
+ </div>
+
+ <h1><a name="5.8LinkBuilder-LinkBuilders"></a>Link Builders</h1>
+
+<p>The LinkBuilders interface enables access to two types of links builders, the SystemLinksBuilder and the SingleLinkBuilder. An instance of LinkBuilders is injected into a class field or method parameter using the @Context annotation.</p>
+
+<p>Upon creation, the LinkBuilders automatically detects if the target method being invoked is a resource method or a sub-resource method. The "resource" and "subResource" properties of the builder are initialized accordingly. The link builder interfaces reside in the org.apache.wink.server.utils package.</p>
+
+
+<h2><a name="5.8LinkBuilder-LinkBuildersOverview"></a>Link Builders Overview</h2>
+
+<p>The JAX-RS specification defines the UriBuilder interface used to construct a URI from a template, but does not specify any mechanism that can automatically generate all resource links.<br/>
+Apache Wink provides the SystemLinksBuilder for automatic generation of all the alternate links to a resource, one link per every supported media type. For example, this is useful for an application that produces Atom feeds to include in the feed all the alternate representations of the resource.</p>
+
+
+<p>Apache Wink provides a mechanism for defining if the generated links should be absolute links or relative to a base URI. For example, links embedded in an Atom feed should be as short as possible in order to optimize the payload size.</p>
+
+
+<h3><a name="5.8LinkBuilder-The%22alt%22QueryParameter"></a>The "alt" Query Parameter</h3>
+
+<p>Apache Wink supports the special query parameter "alt" that is used to override the value of the request Accept header. When the link builders generate a link that specifies the "type" attribute, then the "alt" query parameter is automatically added to the generated link. This is controlled by setting the wink.addAltParam key of the configuration properties file or by calling the LinksBuilder#addAltParam() method.</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 on the Configuration Properties File refer to section <a href="5.1 Registration and Configuration.html#5.1RegistrationandConfiguration-ProviderPriorities">5.1 Registration and Configuration</a>.</td></tr></table></div>
+
+<h2><a name="5.8LinkBuilder-SystemLinksBuilder"></a>System Links Builder</h2>
+
+<p>The SystemLinksBuilder interface enables the generation of all, or a subset of, the system links to a resource or its sub-resources. The links are generated as absolute URIs or as relative to the base URI according to the SystemLinksBuilder state, request information or the application configuration.</p>
+
+<h3><a name="5.8LinkBuilder-Example"></a>Example</h3>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+@Path(<span class="code-quote">"defects/{id}"</span>)
+public class DefectResource {
+@GET
+@Produces(<span class="code-quote">"application/atom+xml"</span>)
+public SyndEntry getAtom() { ... }
+@GET
+@Produces(<span class="code-quote">"application/json"</span>)
+public JSONObject getJson() { ... }
+}
+@GET
+@Produces(<span class="code-quote">"application/xml"</span>)
+public Defect getXml(@Context LinkBuilders linkBuilders) { SystemLinksBuilder builder = linkBuilders.systemLinksBuilder(); ListsystemLinks = builder.build(null); ... }
+}
+</pre>
+</div></div>
+
+<h3><a name="5.8LinkBuilder-Explanation"></a>Explanation</h3>
+
+<p>The DefectResource#getXml() method is invoked when a GET request for application/xml is made to /defects/3. The Apache Wink runtime injects an instance of LinkBuilders to the linkBuilder parameter and a new instance of a SystemLinksBuilder is created by invoking the systemLinksBuilder() method.<br/>
+The call to the build() method of the SystemLinksBuilder generates three alternate links to the DefectResource and the self link:</p>
+
+
+<ul>
+ <li><link rel="self" href="/defects/3"/></li>
+</ul>
+
+
+<ul>
+ <li><link rel="alternate" type="application/json" href="/defects/3"/></li>
+</ul>
+
+
+<ul>
+ <li><link rel="alternate" type="application/xml" href="/defects/3"/></li>
+</ul>
+
+
+<ul>
+ <li><link rel="alternate" type="application/xtom+xml" href="/defects/3"/></li>
+</ul>
+
+
+<h2><a name="5.8LinkBuilder-SingleLinkBuilder"></a>Single Link Builder</h2>
+
+<p>The SingleLinkBuilder interface enables the generation of a single link referencing a resource or a sub-resource, allowing the specification of the 'rel' and 'type' attributes of the generated link. The links are generated as absolute URIs or as relative to the base URI according to the SingleLinkBuilder state, request information or the application configuration.<br/>
+Generating Absolute or Relative Links<br/>
+The link builders generate absolute or relative links based on the following algorithm:</p>
+
+<ol>
+ <li>Use the value that was passed to the relativize() method of the builder.</li>
+ <li>If the relativize() method was not called, then use the value of the "relative-urls" query parameter from the request. The value must be either true or false.</li>
+ <li>If the request does not contain the "<b>relative-urls</b>" query parameter, then use the value of the wink.defaultUrisRelative key set in the application configuration properties file. The value must be either true or false.</li>
+ <li>If the configuration key does not exist, then use true.</li>
+</ol>
+
+
+
+<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 on the Configuration Properties File refer to section <a href="5.1 Registration and Configuration.html#5.1RegistrationandConfiguration-ProviderPriorities">5.1 Registration and Configuration</a>.</td></tr></table></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>
\ No newline at end of file
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/5.9 Assets.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/5.9%20Assets.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/5.9 Assets.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/5.9 Assets.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,291 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 5.9 Assets</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.9 Assets
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h1><a name="5.9Assets-Assets"></a>Assets</h1>
+
+<p>An Asset is a special entity that is returned by a resource method or is injected into a resource method as an entity parameter. The asset is used for retrieving the actual request entity or response entity.<br/>
+The purpose of an asset is to act as a container of an entity data model while providing the transformation methods of the data model into data models of other representations.<br/>
+Asset classes are POJOs, annotated with the @Asset annotation, that have any number of entity methods.</p>
+
+<p>When an asset instance is returned from a resource method or is set as the entity on a Response instance, it is used by the Apache Wink runtime to retrieve the actual response entity by invoking the appropriate entity-producing method of the 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 on Entity-Producing Methods refer to section <a href="#5.9Assets-EntityProducingMethods">Entity Producing Methods</a>.</td></tr></table></div>
+
+<p>When an asset is the entity parameter of a resource method, it is used by the Apache Wink runtime to set the actual request entity by invoking the appropriate entity-consuming method of the asset.</p>
+
+<h2><a name="5.9Assets-AssetsOverview"></a>Assets Overview</h2>
+
+<p>A typical application exposes each resource in a number of representations. Some form of data model usually backs the resource, and the application business logic relies on the manipulation of that data model. The application will most likely expose resource methods allowing the consumption of the data model in more than one representation (for example Atom and XML) and the production of the data model in other representation (for example Atom, XML and JSON).</p>
+
+<p>According to the JAX-RS specification, the optimal method for implementing a resource is one that consumes and produces an application data model and makes use of a different provider for every media type.</p>
+
+<p>For example, if a resource implements methods that consume and produce a "Defect" bean, then a provider must be implemented for each representation of the "Defect" (Atom, XML and JSON). However, there are times that the transformation of the application data model into a representation requires information that may only be available to the resource but is unavailable to a provider (for example, a connection to the Database).</p>
+
+<p>There are several solutions for dealing with the problem of a provider not having sufficient information to perform application data transformations. The following is a description of two possible solutions:</p>
+
+<ul>
+ <li>Passing the information as members on the resource and accessing the resource from the provider via the UriInfo context.</li>
+</ul>
+
+
+<p>This solution is only plausible if the resource scope is "per request" and does not work if the resource is a singleton.</p>
+
+<ul>
+ <li>Passing the information from the resource to the provider via the attributes of the HttpServletRequest.</li>
+</ul>
+
+
+<p>This solution is only plausible when the application is deployed in a JEE container and is not the optimal solution.<br/>
+In addition to the previously mentioned problem, the creation of a provider for every data model per media type may result in the inflation of providers in the system, causing the provider selection algorithm to consider a large set of potential providers.</p>
+
+<p>As a result, the selection of the actual provider from the set of potential providers is non-deterministic, because the selection between them is undefined.</p>
+
+
+<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>Performance Degradation</b><br />An additional side effect of provider inflation is performance degradation.</td></tr></table></div>The use of an asset solves the problem of passing information between a resource and a provider and reduces the amount of registered providers in the system.</p>
+
+<h2><a name="5.9Assets-Lifecycle"></a>Lifecycle</h2>
+
+<p>Resource methods can use an asset as a response entity and as a request entity. The Apache Wink runtime applies different lifecycles for each case.</p>
+
+<h3><a name="5.9Assets-ResponseEntityAsset"></a>Response Entity Asset</h3>
+
+<p>The lifecycle of an asset as a response entity is as follows:</p>
+<ol>
+ <li>The application creates and returns the asset from the resource method.</li>
+ <li>The appropriate entity-producing method is invoked by the Apache Wink runtime to retrieve the actual response entity.</li>
+ <li>The appropriate message body writer as obtained from the Providers#getMessageBodyWriter() method serializes the entity obtained at the previous step.</li>
+ <li>The asset is made available for garbage collection.</li>
+</ol>
+
+
+
+
+
+
+<h3><a name="5.9Assets-RequestEntityAsset"></a>Request Entity Asset</h3>
+
+<p>The lifecycle of an asset as a request entity is as follows:</p>
+
+<ol>
+ <li>An asset class is instantiated by the Apache Wink runtime by invoking the asset default constructor. Note that this implies that the asset class must have a public default constructor.</li>
+ <li>The appropriate message body reader as obtained from the Providers#getMessageBodyReader() method is invoked by the Apache Wink runtime to read the request entity.</li>
+ <li>The appropriate entity-consuming method is invoked on the asset to populate the asset with the request entity.</li>
+ <li>The asset is injected into the resource method as the entity parameter.</li>
+ <li>The asset is made available for garbage collection after returning from the resource method.</li>
+</ol>
+
+
+
+
+
+
+
+<h3><a name="5.9Assets-AssetEntityMethods"></a>Asset Entity Methods</h3>
+
+<p>Asset Entity methods are the public methods of an asset annotated with either @Consumes or @Produces annotation. Annotating a method with both @Consumes and @Produces annotations is not supported and may result in unexpected behavior.</p>
+
+<h3><a name="5.9Assets-EntityProducingMethods"></a>Entity Producing Methods</h3>
+
+<p>An Entity Producing Method is a public asset method annotated with the @Produces annotation, designating it to produce the actual response entity. Such methods produce an entity only for the media types declared in the @Produces annotation. Note that under this definition, wildcard ("<b>/</b>") is allowed.<br/>
+The Apache Wink runtime will not invoke an entity-producing method whose effective value of @Produces does not match the request Accept header</p>
+
+<h3><a name="5.9Assets-EntityConsumingMethods"></a>Entity Consuming Methods</h3>
+
+<p>An Entity Consuming Method is a public asset method annotated with the @Consumes annotation, designating it to consume the actual request entity for populating the asset. Such methods consume an entity only for the media types declared in the @Consumes annotation. Note that under this definition, wildcard ("<b>/</b>") is allowed.<br/>
+The Apache Wink runtime will not invoke an entity-consuming method whose effective value of @Consumes does not match the request Content-Type header.</p>
+
+<h2><a name="5.9Assets-Parameters"></a>Parameters</h2>
+
+<p>Asset Entity methods support the same parameter types as JAX-RS specifies for a resource method.</p>
+
+
+<h2><a name="5.9Assets-ReturnType"></a>Return Type</h2>
+
+<p>Entity methods may return any type that is permissible to return from a resource method.</p>
+
+<h2><a name="5.9Assets-Exceptions"></a>Exceptions</h2>
+
+<p>Exceptions thrown from an entity method are treated as exceptions thrown from a resource method.</p>
+
+<h2><a name="5.9Assets-AnnotationInheritance"></a>Annotation Inheritance</h2>
+
+<p>The @Produces and @Consumes annotations are not inherited when an asset sub-class overrides an asset entity method. Asset sub-classes must re-declare the @Produces and @Consumes annotations for the overriding method to be an entity method.</p>
+
+<h2><a name="5.9Assets-EntityMethodMatching"></a>Entity Method Matching</h2>
+
+<p>Asset classes are handled by the AssetProvider which is a JAX-RS provider that is capable of consuming and producing all media types.</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 on Asset Providers refer to section 7.7 Assets Provider.</td></tr></table></div>
+
+<h3><a name="5.9Assets-RequestEntityMatching"></a>Request Entity Matching</h3>
+
+<p>The following points describe the process of selecting the asset entity-consuming method to handle the request entity. This process occurs during the invocation of the <b>AssetProvider#isReadable()</b> method.</p>
+
+<ol>
+ <li>Collect all the entity-consuming methods of the asset. These are the public methods annotated with @Consumes annotation.</li>
+ <li>Sort the collected entity-consuming methods in descending order, where methods with more specific media types precede methods with less specific media types, following the rule n/m > n/* > <b>/</b>.</li>
+ <li>Select the first method that supports the media type of the request entity body as provided to the AssetProvider#isReadable() method, and return true.</li>
+ <li>If no entity-consuming method supports the media type of the request entity body, return false. The Apache Wink runtime continues searching for a different provider to handle the asset as a regular entity.</li>
+</ol>
+
+
+
+
+
+
+<h3><a name="5.9Assets-ResponseEntityMatching"></a>Response Entity Matching</h3>
+
+<p>The following points describe the process of selecting an entity-producing method to produce the actual response entity. The following process occurs during the invocation of the <b>AssetProvider#isWriteable()</b> method.</p>
+<ol>
+ <li>Collect all the entity-producing methods of the asset. These are the public methods annotated with @Produces annotation.</li>
+ <li>Sort the collected entity-producing methods in descending order, where methods with more specific media types precede methods with less specific media types, following the rule n/m > n/* > <b>/</b>.</li>
+ <li>Select the first method that supports the media type of the response entity body as provided to the AssetProvider#isWriteable()method and return true.</li>
+ <li> If no entity-producing method supports the media type of the response entity body, return false. The Apache Wink runtime continues searching for a different provider to handle the asset as a regular entity.</li>
+</ol>
+
+
+
+
+
+
+<h2><a name="5.9Assets-AssetExample"></a>Asset Example</h2>
+
+<p>The following example illustrates the use of an asset. The "<b>Defect</b>" bean is a JAXB annotated class.</p>
+
+
+<h3><a name="5.9Assets-DefectAssetClass"></a>DefectAsset Class</h3>
+
+<p>The DefectAsset class is the asset backed by an instance of a "Defect" bean.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">@Asset
+public class DefectAsset {
+ public Defect defect;
+ public DefectAsset(Defect defect) {
+ this.defect = defect;
+ }
+ @Produces(<span class="code-quote">"application/xml"</span>)
+ public Defect getDefect() {
+ return this.defect;
+ }
+ @Produces(<span class="code-quote">"text/html"</span>)
+ public String getDefectAsHtml() {
+ String html = ...;
+ return html;
+ }
+
+ @Produces(<span class="code-quote">"application/atom+xml"</span>)
+ public AtomEntry getDefectAsAtom() {
+ AtomEntry entry = ...;
+ return entry;
+ }
+ @Consumes(<span class="code-quote">"application/xml"</span>)
+ public void setDefect(Defect defect) {
+ this.defect = defect;
+ }
+}
+</pre>
+</div></div>
+
+<h3><a name="5.9Assets-DefectResourceClass"></a>DefectResource Class</h3>
+
+<p> The DefectResource class is a resource that is anchored to the URI path "<b>defects/{id}</b>" within the Apache Wink runtime.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">@Path(<span class="code-quote">"defects/{id}"</span>)
+public class DefectResource {
+ @GET
+ public DefectAsset getDefect(@PathParam(<span class="code-quote">"id"</span>) String id) {
+ return new DefectAsset(defects.get(id));
+ }
+ @PUT
+ public DefectAsset updateDefect(DefectAsset defectAsset,
+ @PathParam(<span class="code-quote">"id"</span>) String id) {
+ defects.put(id, defectAsset.getDefect());
+ return defectAsset;
+ }
+}
+</pre>
+</div></div>
+
+<h4><a name="5.9Assets-ScenarioExplanation1"></a>Scenario Explanation 1</h4>
+
+<ol>
+ <li>A client issues an HTTP GET request with a URI="/defects/1" and Accept Header= "application/xm</li>
+ <li>The Apache Wink runtime analyzes the request and invokes the DefectResource#getDefect() resource method.</li>
+ <li>The DefectResource#getDefect() resource method creates an instance of DefectAsset and populates it with defect "1" data</li>
+ <li>The DefectResource#getDefect() resource method returns the DefectAsset instance back to Apache Wink runtim</li>
+ <li>The Apache Wink runtime analyzes the asset and invokes the DefectAsset#getDefect() entity-producing method to obtain the reference to the "Defect" bean.</li>
+ <li>The "Defect" bean is serialized by Apache Wink runtime as an XML using the appropriate provider.</li>
+</ol>
+
+
+
+
+
+
+
+
+
+<h4><a name="5.9Assets-ScenarioExplanation2"></a>Scenario Explanation 2</h4>
+
+
+<ol>
+ <li>A Client issues an HTTP GET request with a URI="/defects/1" and Accept Header= "text/html"</li>
+ <li>The Apache Wink runtime analyzes the request and invokes the DefectResource#getDefect() resource metho</li>
+ <li>The DefectResource#getDefect() resource method creates an instance of DefectAsset and populates it with defect "1" data.</li>
+ <li>The DefectResource#getDefect() method returns the populated asset back to the Apache Wink runtime.</li>
+ <li>The Apache Wink runtime analyzes the asset and invokes the DefectAsset#getDefectAsHtml() entity-producing method in order to obtain the reference to the "Defect" bean.</li>
+ <li>The "Defect" is serialized by Apache Wink runtime as an HTML using the appropriate provider.</li>
+</ol>
+
+
+
+
+
+
+
+
+
+<h4><a name="5.9Assets-ScenarioExplanation3"></a>Scenario Explanation 3</h4>
+
+
+<ol>
+ <li>A Client issues an HTTP PUT request with a URI="/defects/1" and Accept Header= "text/html"</li>
+ <li>The Apache Wink runtime analyzes the request and invokes the DefectResource#updateDefect() method with an instance of DefectAsset populated with the request entity.* A DefectAsset is instantiated by the Apache Wink runtime</li>
+ <li>The DefectAsset#setDefect() entity-consuming method is invoked in order to populate the DefectAsset with the defect data.</li>
+</ol>
+
+
+
+ </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>
\ No newline at end of file
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/6 Apache Wink Client.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/6%20Apache%20Wink%20Client.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/6 Apache Wink Client.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/6 Apache Wink Client.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,123 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 6 Apache Wink Client</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 : 6 Apache Wink Client
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 14, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h1><a name="6ApacheWinkClient-ApacheWinkClient"></a>Apache Wink Client</h1>
+
+<p>The following section describes the Apache Wink Client and provides a detailed description of the Apache Wink Client component and its functionality.</p>
+
+<h3><a name="6ApacheWinkClient-"></a></h3>
+
+
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'><h3><a name="6ApacheWinkClient-Contents"></a>Contents </h3></th>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="6.1 Getting Started with Apache Wink Client.html" title="6.1 Getting Started with Apache Wink Client">6.1 Getting Started with Apache Wink Client</a><br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="6.2 Configuring the Apache Wink Client.html" title="6.2 Configuring the Apache Wink Client">6.2 Configuring the Apache Wink Client</a><br clear="all" /> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="6.3 Input and Output Stream Adapters.html" title="6.3 Input and Output Stream Adapters">6.3 Input and Output Stream Adapters</a><br clear="all" /> </td>
+</tr>
+</tbody></table>
+
+
+
+
+<h2><a name="6ApacheWinkClient-ApacheWinkClientOverview"></a>Apache Wink Client Overview</h2>
+
+<p>The Apache Wink Client is an easy-to-use client, providing a high level Java API for writing clients that consume HTTP-based RESTful Web Services. The Apache Wink Client utilizes JAX-RS concepts, encapsulates Rest standards and protocols and maps Rest principles concepts to Java classes, which facilitates the development of clients for any HTTP-based Rest Web Services.</p>
+
+<p>The Apache Wink Client also provides a Handlers mechanism that enables the manipulation of HTTP request/response messages.</p>
+
+<h2><a name="6ApacheWinkClient-MainFeatures"></a>Main Features</h2>
+
+<p>The Apache Wink Clients main features are as follows:</p>
+
+
+
+
+<ul>
+ <li>Utilizes JAX-RS Providers for resource serialization and deserialization</li>
+ <li>Provides Java object models for Atom, Json, RSS, APP, CSV, Multipart and OpenSearch along with providers to serialize and deserialize these models</li>
+ <li>Uses the JDK HttpUrlConnection as the underlying Http transport</li>
+ <li>Allows for the easy replacement of the underlying Http transport</li>
+ <li>Provides a Handlers mechanism for manipulation of HTTP request and response messages</li>
+</ul>
+
+
+<h3><a name="6ApacheWinkClient-Supports"></a>Supports</h3>
+
+
+<ul>
+ <li>Http proxy</li>
+ <li>SSL</li>
+</ul>
+
+
+<h2><a name="6ApacheWinkClient-"></a></h2>
+
+
+<h3><a name="6ApacheWinkClient-ApacheWinkHighLevelClientArchitectureOverview"></a>Apache Wink High Level Client Architecture Overview</h3>
+
+<p>The following diagram illustrates the high-level architecture of the Apache Wink Client.</p>
+
+<h3><a name="6ApacheWinkClient-"></a></h3>
+
+<p><img src="attachments/2851055/3112983.jpg" align="absmiddle" border="0"/></p>
+
+<p>The RestClient class is the Apache Wink Client entry point and is responsible for holding different configuration options and the provider registry.</p>
+
+
+
+
+<p>The RestClient is used to create instances of the Resource class. The Resource class represents a web resource associated with a specific URI and is used to perform uniform interface operations on the resource it represents. Every method invocation goes through a user defined handlers chain that enables for manipulation of the request and response.</p>
+
+ <br/>
+ <div class="tabletitle">
+ <a name="attachments">Attachments:</a>
+ </div>
+
+ <div class="greybox" align="left">
+ <img src="images/icons/bullet_blue.gif" height="8" width="8" alt=""/>
+ <a href="attachments/2851055/3112970.jpg">Wink Logo.jpg</a> (image/jpeg)
+ <br/>
+ <img src="images/icons/bullet_blue.gif" height="8" width="8" alt=""/>
+ <a href="attachments/2851055/3112983.jpg">Symphony 2.0 Client Diagram.jpg</a> (image/jpeg)
+ <br/>
+ </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>
\ No newline at end of file
Propchange: incubator/wink/site/trunk/src/site/resources/1.0/html/6 Apache Wink Client.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/6.1 Getting Started with Apache Wink Client.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/6.1%20Getting%20Started%20with%20Apache%20Wink%20Client.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/6.1 Getting Started with Apache Wink Client.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/6.1 Getting Started with Apache Wink Client.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,133 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 6.1 Getting Started with Apache Wink Client</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 : 6.1 Getting Started with Apache Wink Client
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h2><a name="6.1GettingStartedwithApacheWinkClient-GettingStartedwiththeApacheWinkClient"></a>Getting Started with the Apache Wink Client</h2>
+
+<p>The following section details the getting started examples that demonstrate how to write a simple client that consume RESTful Web Services with the Apache Wink Client.</p>
+
+<h3><a name="6.1GettingStartedwithApacheWinkClient-GETRequest"></a>GET Request</h3>
+
+<p>The following example demonstrates how to issue an Http GET request.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">// create the rest client instance
+1 RestClient client = new RestClient();
+
+// create the resource instance to interact with
+2 Resource resource = client.resource(<span class="code-quote">"http://services.com/HelloWorld"</span>);
+// perform a GET on the resource. The resource will be returned as plain text
+3 String response = resource.accept(<span class="code-quote">"text/plain"</span>).get(String.class);
+</pre>
+</div></div>
+
+<h4><a name="6.1GettingStartedwithApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>The RestClient is the entry point for building a RESTful Web Service client. In order to start working with the Wink Client, a new instance of RestClient needs to be created, as the example shows in line 1 of the example. A new Resource is then created with the given URI, by calling the RestClient#resource() method as appears in line 2.</p>
+
+<p>Finally, the Resource#get() method is invoked in order to issue an Http GET request as appears in line 3.<br/>
+Once the Http response is returned, the client invokes the relevant provider to desterilizes the response in line 3.</p>
+
+<h3><a name="6.1GettingStartedwithApacheWinkClient-POSTRequest"></a>POST Request</h3>
+
+<p>The following example demonstrates how to issue an Http POST request.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">// create the rest client instance
+1 RestClient client = new RestClient();
+
+// create the resource instance to interact with
+2 Resource resource = client.resource(<span class="code-quote">"http://services.co"</span>);
+
+// issue the request
+3 String response = resource.contentType(<span class="code-quote">"text/plain"</span>).accept(<span class="code-quote">"text/plain"</span>).post(String.class, <span class="code-quote">"foo"</span>);
+</pre>
+</div></div>
+
+<h4><a name="6.1GettingStartedwithApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>The POST Request example demonstrates how to issue a simple Http POST request that sends and receives resources as strings.</p>
+
+<p>First, a new instance of a Resource is created through the RestClient. The Http POST request is then issued by specifying the request and response media types and the response entity type (String.class).</p>
+
+<h3><a name="6.1GettingStartedwithApacheWinkClient-POSTAtomRequest"></a>POST Atom Request</h3>
+
+<p>The following example demonstrates how to issue an Http POST request that sends and receives atom entries.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">// create the rest client instance
+1 RestClient client = new RestClient();
+
+// create the resource instance to interact with
+2 Resource resource = client.resource(<span class="code-quote">"http://services.co"</span>);
+
+3 AtomEntry request = getAtomEntry();
+
+// issue the request
+4 AtomEntry response = resource.contentType(<span class="code-quote">"application/atom+xml"</span>).accept(<span class="code-quote">"application/atom+xml"</span>).post(AtomEntry.class, request);
+</pre>
+</div></div>
+
+<h4><a name="6.1GettingStartedwithApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>The Apache Wink Client provides an object model for Atom (atom feed and atom entry), and supplies out-of-the-box providers that enable sending and receiving atom feeds and entries.</p>
+
+<h3><a name="6.1GettingStartedwithApacheWinkClient-UsingClientResponse"></a>Using ClientResponse</h3>
+
+<p>The following example demonstrates how to use the ClientResponse object in order to de-serialize the response entity.</p>
+
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">// create the rest client instance
+1 RestClient client = new RestClient();
+
+// create the resource instance to interact with
+2 Resource resource = client.resource(<span class="code-quote">"http://services.co"</span>);
+
+// issue the request
+3 ClientResponse response = resource.accept(<span class="code-quote">"text/plain"</span>).get();
+
+// deserialize response
+4 String responseAsString = response.getEntity(String.class);
+</pre>
+</div></div>
+
+<h4><a name="6.1GettingStartedwithApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>If the response entity type is not provided when invoking the Resource#get() method that appears in line 3, the response will be returned as the raw ClientResponse. In order to trigger the response deserialization mechanism, the ClientResponse#getEntity() method needs to be invoked as it appears in line 4 with the required response entity type.</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>
\ No newline at end of file
Propchange: incubator/wink/site/trunk/src/site/resources/1.0/html/6.1 Getting Started with Apache Wink Client.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/6.2 Configuring the Apache Wink Client.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/6.2%20Configuring%20the%20Apache%20Wink%20Client.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/6.2 Configuring the Apache Wink Client.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/6.2 Configuring the Apache Wink Client.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,116 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 6.2 Configuring the Apache Wink Client</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 : 6.2 Configuring the Apache Wink Client
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h2><a name="6.2ConfiguringtheApacheWinkClient-ClientConfiguration"></a>Client Configuration</h2>
+
+<p>The RestClient configuration is performed by using the ClientConfig class. An instance of the configuration class is passed to the constructor of the RestClient when constructing a new RestClient.</p>
+
+<p>The following options can be configured in the RestClient:</p>
+
+<ul>
+ <li>Custom providers via JAX-RS Application</li>
+</ul>
+
+
+<ul>
+ <li>Handler chain</li>
+</ul>
+
+
+<ul>
+ <li>Proxy host and port</li>
+</ul>
+
+
+<ul>
+ <li>Connect and read timeouts</li>
+</ul>
+
+
+<ul>
+ <li>Redirect</li>
+</ul>
+
+
+<h3><a name="6.2ConfiguringtheApacheWinkClient-HandlerConfiguration"></a>Handler Configuration</h3>
+
+<p>The following example demonstrates how to register a custom handler.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">1 ClientConfig config = new ClientConfig();
+// Create new JAX-RS Application
+2 config.handlers(new DummyHandler());
+// create the rest client instance
+3 RestClient client = new RestClient(config);
+// create the resource instance to interact with
+4 Resource resource = client.resource(<span class="code-quote">"http://services.com/HelloWorld"</span>);
+// perform a GET on the resource
+// the resource will be returned as plain text
+5 String response = resource.accept(<span class="code-quote">"text/plain"</span>).get(String.class);
+</pre>
+</div></div>
+
+<h4><a name="6.2ConfiguringtheApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>First, a new instance of a ClientConfig is created as it appears in line 1. Then the new handler is added to the handlers chain by invoking the handlers() method on the ClientConfig instance as it appears in line 2. Finally, a new instance of a RestClient is created with this configuration as it appears in line 3.</p>
+
+<h3><a name="6.2ConfiguringtheApacheWinkClient-CustomProviderConfiguration"></a>Custom Provider Configuration</h3>
+
+<p>The following example demonstrates how to register a custom entity provider.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">1 ClientConfig config = new ClientConfig();
+ // Create new JAX-RS Application
+2 Application app = new Application() {
+ @Override
+ public Set<span class="code-tag"><Class<?></span>> getClasses() {
+ HashSet<span class="code-tag"><Class<?></span>> set = new HashSet<span class="code-tag"><Class<?></span>>();
+ set.add(FooProvider.class);
+ return set;}};
+3 conf.applications(app);
+// create the rest client instance
+4 RestClient client = new RestClient(config);
+// create the resource instance to interact with
+5 Resource resource = client.resource(<span class="code-quote">"http://services.com/HelloWorld"</span>);
+// perform a GET on the resource. the resource will be returned as plain text
+6 String response = resource.accept(<span class="code-quote">"text/plain"</span>).get(String.class);
+</pre>
+</div></div>
+
+<h4><a name="6.2ConfiguringtheApacheWinkClient-Explanation"></a>Explanation</h4>
+
+<p>First, a new instance of ClientConfig is created as it appears in line 1. Then a new anonymous Application is instantiated and set on the ClientConfig as it appears in line 2 and 3. Finally, a new instance of a RestClient is created with this configuration as it appears in line 4.</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>
\ No newline at end of file
Propchange: incubator/wink/site/trunk/src/site/resources/1.0/html/6.2 Configuring the Apache Wink Client.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/6.3 Input and Output Stream Adapters.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/6.3%20Input%20and%20Output%20Stream%20Adapters.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/6.3 Input and Output Stream Adapters.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/6.3 Input and Output Stream Adapters.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,110 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 6.3 Input and Output Stream Adapters</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 : 6.3 Input and Output Stream Adapters
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h2><a name="6.3InputandOutputStreamAdapters-InputandOutputStreamAdapters"></a>Input and Output Stream Adapters</h2>
+
+<p>The Apache Wink Client provides the ability to manipulate raw Http input and output entity streams through the InputStreamAdapter and the OutputStreamAdapter interfaces. This is useful for modifying the input and output streams, regardless of the actual entity, for example when adding compression capabilities.<br/>
+The adapt() method of the output stream adapter is called before the request headers are committed, in order to allow the adapter to manipulate them.</p>
+
+<p>The adapt() method of the input stream adapter is called after the response status code and the headers are received in order to allow the adapter to behave accordingly.</p>
+
+<h3><a name="6.3InputandOutputStreamAdapters-StreamAdaptersExample"></a>Stream Adapters Example</h3>
+
+<p>The following example demonstrates how to implement input and output adapters.</p>
+
+<h3><a name="6.3InputandOutputStreamAdapters-GzipHandler"></a>Gzip Handler</h3>
+
+<p>The following code snippet is an example of adding a input and output adapters in the Gzip handler.</p>
+
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">public class GzipHandler implements ClientHandler {
+ public ClientResponse handle(ClientRequest request,
+ HandlerContext context) {
+ request.getHeaders().add(<span class="code-quote">"Accept-Encoding"</span>, <span class="code-quote">"gzip"</span>);
+ context.addInputStreamAdapter(new GzipInputAdapter());
+ context.addOutputStreamAdapter(new GzipOutputAdapter());
+ return context.doChain(request);
+ }}
+</pre>
+</div></div>
+
+<h4><a name="6.3InputandOutputStreamAdapters-Explanation"></a>Explanation</h4>
+
+<p>The Gzip handler creates instances of the <b>GzipInputAdapter</b> and the <b>GzipOutputAdapter</b> and adds them to the stream adapters of the current request by invoking the <b>addInputStreamAdapter()</b> method and the <b>addOutputStreamAdapter()</b> method on the HandlerContext instance.</p>
+
+<h3><a name="6.3InputandOutputStreamAdapters-GzipInputStreamAdapter"></a>Gzip Input Stream Adapter</h3>
+
+<p>The following code snippet is an example of an implementation of a Gzip input stream adapter.</p>
+
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">class GzipInputAdapter implements InputStreamAdapter{
+ public InputStream adapt(InputStream is,
+ ClientResponse response) {
+ String header = response.getHeaders().getFirst(<span class="code-quote">"Content-Encoding"</span>);
+ if (header != null && header.equalsIgnoreCase(<span class="code-quote">"gzip"</span>)) {
+ return new GZIPInputStream(is);
+ }
+ return is;
+ }}
+</pre>
+</div></div>
+
+<h4><a name="6.3InputandOutputStreamAdapters-Explanation"></a>Explanation</h4>
+
+<p>The Gzip input stream adapter is responsible for wrapping the input stream with the Gzip input stream.</p>
+
+<h3><a name="6.3InputandOutputStreamAdapters-GzipOutputStreamAdapter"></a>Gzip Output Stream Adapter</h3>
+
+<p>The following code snippet is an example of an implementation of a Gzip output stream adapter.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">class GzipOutputAdapter implements OutputStreamAdapter {
+ public OutputStream adapt(OutputStream os,
+ ClientRequest request) {
+ request.getHeaders().add(<span class="code-quote">"Content-Encoding"</span>, <span class="code-quote">"gzip"</span>);
+ return new GZIPOutputStream(os);
+ }}
+</pre>
+</div></div>
+
+<h4><a name="6.3InputandOutputStreamAdapters-Explanation"></a>Explanation</h4>
+
+<p>The Gzip output stream adapter is responsible for wrapping the output stream with the Gzip output stream. </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>
\ No newline at end of file
Propchange: incubator/wink/site/trunk/src/site/resources/1.0/html/6.3 Input and Output Stream Adapters.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/7 Apache Wink Representations.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/7%20Apache%20Wink%20Representations.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/7 Apache Wink Representations.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/7 Apache Wink Representations.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,160 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 7 Apache Wink Representations</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 : 7 Apache Wink Representations
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 14, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h1><a name="7ApacheWinkRepresentations-ApacheWinkRepresentations"></a>Apache Wink Representations</h1>
+
+<p>In addition to the JAX-RS standard representations Apache Wink provides an expanded set of representations that can be used by an application to expose resources in a rich set of representations. The following section provides information about the representations that are supported by Apache Wink.</p>
+
+
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'><h3><a name="7ApacheWinkRepresentations-Contents"></a>Contents </h3></th>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.1 JSON.html" title="7.1 JSON">7.1 Json </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.2 APP.html" title="7.2 APP">7.2 APP </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.3 Atom.html" title="7.3 Atom">7.3 Atom </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.4 RSS.html" title="7.4 RSS">7.4 RSS</a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.5 HTML.html" title="7.5 HTML">7.5 HTML </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.6 CSV.html" title="7.6 CSV">7.6 CSV </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.7 OpenSearch.html" title="7.7 OpenSearch">7.7 OpenSearch </a> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> <a href="7.8 MultiPart.html" title="7.8 MultiPart">7.8 MultiPart</a> </td>
+</tr>
+</tbody></table>
+
+<h3><a name="7ApacheWinkRepresentations-ApacheWinkRepresentationsRequestFlow"></a>Apache Wink Representations Request Flow</h3>
+
+<p>The following diagram illustrates the client request flow for a resource.</p>
+
+<h3><a name="7ApacheWinkRepresentations-"></a></h3>
+
+<p><img src="attachments/2851061/4751375.jpg" align="absmiddle" border="0"/></p>
+
+
+<p>A resource is an abstract entity and as such can not be transmitted between peers. When a client is required to send or receive a resource it must use a representation of that resource. The resource representation is a specific formatting of the resource data. The diagram illustrates that a request for a resource is in fact a request for a specific representation of that resource. </p>
+
+<p>Apache Wink implements resource representations through the use of providers for java objects as defined by the JAX-RS specification.</p>
+
+
+<h3><a name="7ApacheWinkRepresentations-ApacheWinkProviders"></a>Apache Wink Providers</h3>
+
+
+<h3><a name="7ApacheWinkRepresentations-"></a></h3>
+
+<p>In addition to JAX-RS standard providers (<b>refer to section 4.2 of the JAX-RS specification</b>), Apache Wink provides a set of complementary providers. The purpose of these providers is to provide mapping services between various representations for example Atom, APP, OpenSearch, CSV, JSON and HTML, and their associated Java data models.</p>
+
+<p>The Apache Wink providers are pre-registered and delivered with the Apache Wink runtime along with the JAX-RS standard providers.</p>
+
+<p>Apache Wink provides an additional method for defining the life cycle of a provider via the use of the @Scope annotation and a way to define the providers priorities.</p>
+
+<h2><a name="7ApacheWinkRepresentations-"></a></h2>
+
+<h4><a name="7ApacheWinkRepresentations-Scoping"></a>Scoping</h4>
+
+<p>The JAX-RS specification defines by default, that a singleton instance of each provider class is instantiated for each JAX-RS application. Apache Wink fully supports this requirement and in addition provides a "Prototype" lifecycle, which is an instance per-request lifecycle.<br/>
+Prototype means that a new instance of a provider class is instantiated for each request. The @Scope annotation (sectionâ0) is used on a provider class to specify its lifecycle. The lifecycle of a provider that does not specify the @Scope annotation defaults to the singleton lifecycle.</p>
+
+<h4><a name="7ApacheWinkRepresentations-PrototypeExample"></a>Prototype Example</h4>
+
+<p>The following example shows 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 MyProvider implements MessageBodyReader<span class="code-tag"><String></span>{
+ ...
+}
+</pre>
+</div></div>
+
+<h4><a name="7ApacheWinkRepresentations-SingletonExample1"></a>Singleton Example 1</h4>
+
+<p>The following example shows how to define a provider with a singleton lifecycle.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">@Scope(ScopeType.SINGELTON)
+@Provider
+public class MyProvider implements MessageBodyReader<span class="code-tag"><String></span>{
+ ...
+}
+</pre>
+</div></div>
+
+<h4><a name="7ApacheWinkRepresentations-SingletonExample2"></a>Singleton Example 2</h4>
+
+<p>The following example shows that when the @Scope annotation is not used, the provider will be a singleton, as per the JAX-RS specification.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">@Provider
+public class MyProvider implements MessageBodyReader<span class="code-tag"><String></span>{
+ ...
+}
+</pre>
+</div></div>
+
+<h3><a name="7ApacheWinkRepresentations-Priority"></a>Priority</h3>
+
+<p>Apache Wink provides a method for setting a priority for a provider.</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 on Provider Priorities refer to section <a href="5.1 Registration and Configuration.html#5.1RegistrationandConfiguration-ProviderPriorities">5.1 Registration and Configuration</a>.</td></tr></table></div>
+
+ <br/>
+ <div class="tabletitle">
+ <a name="attachments">Attachments:</a>
+ </div>
+
+ <div class="greybox" align="left">
+ <img src="images/icons/bullet_blue.gif" height="8" width="8" alt=""/>
+ <a href="attachments/2851061/4751374.jpg">Apache Wink Representations Diagram.jpg</a> (image/jpeg)
+ <br/>
+ <img src="images/icons/bullet_blue.gif" height="8" width="8" alt=""/>
+ <a href="attachments/2851061/4751375.jpg">Apache Wink Representations Diagram2.jpg</a> (image/jpeg)
+ <br/>
+ </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>
\ No newline at end of file
Added: incubator/wink/site/trunk/src/site/resources/1.0/html/7.1 JSON.html
URL: http://svn.apache.org/viewvc/incubator/wink/site/trunk/src/site/resources/1.0/html/7.1%20JSON.html?rev=834791&view=auto
==============================================================================
--- incubator/wink/site/trunk/src/site/resources/1.0/html/7.1 JSON.html (added)
+++ incubator/wink/site/trunk/src/site/resources/1.0/html/7.1 JSON.html Wed Nov 11 07:39:44 2009
@@ -0,0 +1,270 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+ <head>
+ <title>Apache Wink : 7.1 JSON</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 : 7.1 JSON
+ </span>
+ </div>
+ <div class="pagesubheading">
+ This page last changed on Oct 13, 2009 by <font color="#0050B2">michael</font>.
+ </div>
+
+ <h3><a name="7.1JSON-JSONProviders"></a>JSON Providers</h3>
+
+<p>Apache Wink provides a set providers that are capable of serializing a number of data models into JSON representations. There are currently 3 Apache Wink extensions that provide JSON support. Each has unique features that may make one more suitable for your particular application.</p>
+
+<h3><a name="7.1JSON-winkjsonprovider%28org.json%29"></a>wink-json-provider (org.json)</h3>
+
+<p>The wink-json-provider extension is provided in the binary distribution and uses the <a href="http://json.org">JSON.org</a> classes to provide JSON support. Include the wink-json-provider-<VERSION>.jar in the classpath and the providers will automatically be registered. You will also need the org.json JAR which is provided in the ext/wink-json-provider/lib folder.</p>
+
+<h5><a name="7.1JSON-org.apache.wink.providers.json.JsonProvider"></a>org.apache.wink.providers.json.JsonProvider</h5>
+
+<p>Handles reading and writing of org.json.JSONObject classes for the application/json and application/javascript media types.</p>
+
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'> Supported </th>
+<th class='confluenceTh'> Media Types <br clear="all" /> </th>
+<th class='confluenceTh'> Entity <br clear="all" /> </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Read <br clear="all" /> </td>
+<td class='confluenceTd'> Yes <br clear="all" /> </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> org.json.JSONObject </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Write <br clear="all" /> </td>
+<td class='confluenceTd'> Yes </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> org.json.JSONObject </td>
+</tr>
+</tbody></table>
+
+
+<h5><a name="7.1JSON-org.apache.wink.providers.json.JsonArrayProvider"></a>org.apache.wink.providers.json.JsonArrayProvider</h5>
+
+<p>Handles reading and writing of org.json.JSONArray classes for the application/json and application/javascript media types.</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'> Supported </th>
+<th class='confluenceTh'> Media Types <br clear="all" /> </th>
+<th class='confluenceTh'> Entity <br clear="all" /> </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Read <br clear="all" /> </td>
+<td class='confluenceTd'> Yes <br clear="all" /> </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> org.json.JSONArray </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Write <br clear="all" /> </td>
+<td class='confluenceTd'> Yes </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> org.json.JSONArray </td>
+</tr>
+</tbody></table>
+
+
+<h5><a name="7.1JSON-org.apache.wink.providers.json.JsonJAXBProvider"></a>org.apache.wink.providers.json.JsonJAXBProvider</h5>
+
+<p>Handles reading and writing of JAXBElement and JAXB annotated classes for the application/json and application/javascript media types.</p>
+
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'> Supported </th>
+<th class='confluenceTh'> Media Types <br clear="all" /> </th>
+<th class='confluenceTh'> Entity <br clear="all" /> </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Read <br clear="all" /> </td>
+<td class='confluenceTd'> Yes <br clear="all" /> </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> JAXB object, <br clear="all" />
+JAXBElement<?>>> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Write <br clear="all" /> </td>
+<td class='confluenceTd'> Yes </td>
+<td class='confluenceTd'> application/json , application/javascript <br clear="all" /> </td>
+<td class='confluenceTd'> JAXB object, <br clear="all" />
+JAXBElement<?>>> </td>
+</tr>
+</tbody></table>
+
+
+
+<h3><a name="7.1JSON-ProducingandConsumingJSONExample"></a>Producing and Consuming JSON Example</h3>
+
+<p>The following example demonstrates the usage of a JSON provider for reading and writing JSON representations.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+ @GET
+ @Consumes(MediaType.APPLICATION_JSON)
+ @Produces(MediaType.APPLICATION_JSON)
+ <span class="code-keyword">public</span> JSONObject postJSON(JSONObject requestJSON) {
+ <span class="code-object">String</span> property = requestJSON.getString(<span class="code-quote">"property"</span>);
+ JSONObject jobj = <span class="code-keyword">new</span> JSONObject();
+ <span class="code-keyword">return</span> jobj;
+ }
+
+ /* Book is a JAXB annotated class */
+
+ @GET
+ @Consumes(MediaType.APPLICATION_JSON)
+ @Produces(MediaType.APPLICATION_JSON)
+ <span class="code-keyword">public</span> Book postJSONBook(Book requestBookEntity) {
+ <span class="code-object">String</span> title = requestBookEntity.getTitle();
+ /* other code */
+ Book response = <span class="code-keyword">new</span> Book();
+ <span class="code-keyword">return</span> response;
+ }
+</pre>
+</div></div>
+
+<h3><a name="7.1JSON-winkjettisonprovider%28org.codehaus.jettison%29"></a>wink-jettison-provider (org.codehaus.jettison)</h3>
+
+<p>The wink-jettison-provider extension is provided in the binary distribution and uses the <a href="http://jettison.codehaus.org/">Jettison</a> code to provide JSON support. Include the wink-jettison-provider-<VERSION>.jar in the classpath and the providers will automatically be registered. You will also need the Jettison library JARs which are provided in the ext/wink-jettison-provider/lib folder.</p>
+
+<p>By default, reading is currently disabled due to potential issues with the reader. You can enable it by calling setUseAsReader(boolean) on each provider and registering as a singleton in the JAX-RS Application sub-class.</p>
+
+<h5><a name="7.1JSON-rg.apache.wink.providers.jettison.JettisonJAX..."></a>org.apache.wink.providers.jettison.JettisonJAXBElementProvider</h5>
+
+<p>Handles reading and writing of JAXBElement classes for the application/json media type.</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'> Supported </th>
+<th class='confluenceTh'> Media Types <br clear="all" /> </th>
+<th class='confluenceTh'> Entity <br clear="all" /> </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Read <br clear="all" /> </td>
+<td class='confluenceTd'> Yes <br clear="all" /> </td>
+<td class='confluenceTd'> application/json <br clear="all" /> </td>
+<td class='confluenceTd'> JAXBElement<?>>> </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Write <br clear="all" /> </td>
+<td class='confluenceTd'> Yes </td>
+<td class='confluenceTd'> application/json <br clear="all" /> </td>
+<td class='confluenceTd'> JAXBElement<?>>> </td>
+</tr>
+</tbody></table>
+
+
+<h5><a name="7.1JSON-rg.apache.wink.providers.jettison.JettisonJAX..."></a>org.apache.wink.providers.jettison.JettisonJAXBElementProvider</h5>
+
+<p>Handles reading and writing of JAXB annotated classes for the application/json media type.</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'> Supported </th>
+<th class='confluenceTh'> Media Types <br clear="all" /> </th>
+<th class='confluenceTh'> Entity <br clear="all" /> </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Read <br clear="all" /> </td>
+<td class='confluenceTd'> Yes <br clear="all" /> </td>
+<td class='confluenceTd'> application/json <br clear="all" /> </td>
+<td class='confluenceTd'> JAXB object </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Write <br clear="all" /> </td>
+<td class='confluenceTd'> Yes </td>
+<td class='confluenceTd'> application/json <br clear="all" /> </td>
+<td class='confluenceTd'> JAXB object </td>
+</tr>
+</tbody></table>
+
+
+<h3><a name="7.1JSON-Example"></a>Example</h3>
+
+<p>The following examples demonstrates the usage of a Jettison provider for producing and consuming JSON.</p>
+
+
+<h4><a name="7.1JSON-JettisonProviderRegistration"></a>Jettison Provider Registration</h4>
+
+
+<p>The following code example demonstrates the way to register a Jettison provider within a JAX-RS application.</p>
+
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+ <span class="code-keyword">public</span> class MyApp <span class="code-keyword">extends</span> Application {
+ <span class="code-keyword">public</span> Set getClasses() {
+ Set s = <span class="code-keyword">new</span> HashSet();
+ s.add(MyResource.class);
+ <span class="code-keyword">return</span> s;
+ }
+
+ <span class="code-keyword">public</span> Set<<span class="code-object">Object</span>> getSingletons() {
+ Set s = <span class="code-keyword">new</span> HashSet();
+ JettisonJAXBProvider jaxbProvider = <span class="code-keyword">new</span> JettisonJAXBProvider();
+ jaxbProvider.setUseAsReader(<span class="code-keyword">true</span>);
+ <span class="code-keyword">return</span> s;
+ }
+ }
+</pre>
+</div></div>
+
+<h4><a name="7.1JSON-ProducingandConsumingJSON"></a>Producing and Consuming JSON</h4>
+
+<p>The following code example demonstrates the reading and writting of JAXB objects into a JSON representation by using a Jettison provider.</p>
+
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+ /* Book is a JAXB annotated class */
+
+ @GET
+ @Consumes(MediaType.APPLICATION_JSON)
+ @Produces(MediaType.APPLICATION_JSON)
+ <span class="code-keyword">public</span> Book postJSONBook(Book requestBookEntity) {
+ <span class="code-object">String</span> title = requestBookEntity.getTitle();
+ /* other code */
+ Book response = <span class="code-keyword">new</span> Book();
+ <span class="code-keyword">return</span> response;
+ }
+</pre>
+</div></div>
+
+<h4><a name="7.1JSON-JacksonJSONProcessor"></a>Jackson JSON Processor</h4>
+
+<p><a href="http://jackson.codehaus.org/">Jackson JSON Processor</a> may also suit your needs and can be used. They provide their own JAX-RS entity provider. See their documentation for more information.</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>
\ No newline at end of file