| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>Apache Wink : 5.1 Registration and Configuration</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.1 Registration and Configuration |
| </span> |
| </div> |
| <div class="pagesubheading"> |
| This page last changed on Oct 13, 2009 by <font color="#0050B2">bluk</font>. |
| </div> |
| |
| <h1><a name="5.1RegistrationandConfiguration-RegistrationandConfiguration"></a>Registration and Configuration</h1> |
| |
| <p>Apache Wink provides several methods for registering resources and providers. This chapter describes registration methods and Wink configuration options. </p> |
| |
| <h2><a name="5.1RegistrationandConfiguration-SimpleApplication"></a>Simple Application</h2> |
| |
| <p>Apache Wink provides the "<b>SimpleWinkApplication</b>" class in order to support the loading of resources and providers through a simple text file that contains a list of fully qualified class names of the resource and provider classes. Each line contains a single fully qualified class name that is either a resource or a provider. Empty lines and lines that begin with a number sign (#) are permitted and ignored.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml"># Providers
|
| com.example.MyXmlProvider
|
| com.example.MyJSONProvider
|
|
|
| # Resources
|
| com.example.FooResource
|
| com.example.BarResource
|
| </pre> |
| </div></div> |
| |
| <h4><a name="5.1RegistrationandConfiguration-SpecifyingtheSimpleApplicationFileLocation"></a>Specifying the Simple Application File Location</h4> |
| |
| <p>The path to a simple application file is configured via the applicationConfigLocation init-param in the web.xml file. It is possible to specify multiple files by separating them with a semicolon.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml"><span class="code-tag"><servlet></span>
|
| <span class="code-tag"><servlet-name></span>restSdkService<span class="code-tag"></servlet-name></span>
|
| <span class="code-tag"><servlet-class></span>
|
| org.apache.wink.server.internal.servlet.RestServlet
|
| <span class="code-tag"></servlet-class></span>
|
| <span class="code-tag"><init-param></span>
|
| <span class="code-tag"><param-name></span>applicationConfigLocation<span class="code-tag"></param-name></span>
|
| <span class="code-tag"><param-value></span>/WEB-INF/providers;/WEB-INF/resources<span class="code-tag"></param-value></span>
|
| <span class="code-tag"></init-param></span>
|
| <span class="code-tag"></servlet></span>
|
| </pre> |
| </div></div> |
| |
| <h3><a name="5.1RegistrationandConfiguration-ApacheWinkApplication"></a>Apache Wink Application</h3> |
| |
| <p>Apache Wink extends the javax.ws.rs.core.Application class with the org.apache.wink.common.WinkApplication class in order to provide the Dynamic Resources and the Priorities functionality.</p> |
| |
| <p>An application may provide an instance of the Apache Wink Application to the Apache Wink runtime as specified by the JAX-RS specification.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-DynamicResources"></a>Dynamic Resources</h3> |
| |
| <p>Dynamic Resources enable the binding of a Resource class to a URI path during runtime instead of by using the @Path annotation. A dynamic resource must implement the DynamicResource interface and must not be annotated with the @Path annotation.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-Motivation"></a>Motivation</h3> |
| |
| <p>A Dynamic Resource is useful for situations where a resource class must be bound to multiple paths, for example, a sorting resource:</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">
|
| <span class="code-keyword">public</span> class SortingResource<E <span class="code-keyword">extends</span> Comparable<? <span class="code-keyword">super</span> E>> {
|
| <span class="code-keyword">private</span> List<E> list;
|
| @POST
|
| <span class="code-keyword">public</span> void sort() {
|
| Collections.sort(list);
|
| }
|
| <span class="code-keyword">public</span> void setList(List<E> list) {
|
| <span class="code-keyword">this</span>.list = list;
|
| }
|
| <span class="code-keyword">public</span> List<E> getList() {
|
| <span class="code-keyword">return</span> list;
|
| }
|
| }
|
| </pre> |
| </div></div> |
| |
| <h5><a name="5.1RegistrationandConfiguration-Explanation"></a>Explanation</h5> |
| |
| <p>In this example, the SortingResource class can sort any list. If the application manages a library of books and exposes the following resource paths, then the SortingResource class can be used for the implementation of all these resource paths, assuming that it could be bound to more than one path.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml">/sort-books
|
| /sort-authors
|
| /sort-titles
|
| </pre> |
| </div></div> |
| <p>A dynamic resource is also useful for situations where the resource path is unknown during development, and is only known during the application startup.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-Usage"></a>Usage</h3> |
| |
| <p>A Dynamic Resource is a resource class that implements the org.apache.wink.server.DynamicResource interface or extends the org.apache.wink.server.AbstractDynamicResource convenience class.</p> |
| |
| <p>A Dynamic Resource is not registered in Apache Wink through the Application#getClasses() method or the Application#getSignletons() method, since the same class can be used for multiple resources.<br/> |
| In order to register Dynamic Resources in the system, the WinkApplication#getInstances()method must be used.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-Scope"></a>Scope</h3> |
| |
| <p>The scope of a Dynamic Resource is limited to "singleton" as it is initialized prior to its registration, and the system does not have enough information to create it in runtime. This limitation is irrelevant when working with Spring. Refer to chapter 0 for more information on Spring integration.</p> |
| |
| |
| <h2><a name="5.1RegistrationandConfiguration-Priorities"></a>Priorities</h2> |
| |
| <p>Although JAX-RS defines the algorithm for searching for resources and providers, Apache Wink enables to extend this algorithm by allowing the specification of priorities for them.<br/> |
| Apache Wink extends the JAX-RS search algorithms by providing the ability to specify priorities on the resources and providers. This is achieved by enabling the registration of multiple Application instances with different priorities, rendering the order of their registration irrelevant as long as they have different priorities.</p> |
| |
| <p>In order to register a prioritized Application, it is necessary to register an instance of a Apache WinkApplication class. Priority values range between 0 and 1. In the event that the priority was not specified, a default priority of 0.5 is used.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-ResourcePriorities"></a>Resource Priorities</h3> |
| |
| <p>Priorities on resources are useful for situations where an application registers core resources bound to paths, and allows extensions to register resources on the same paths in order to override the core resources.</p> |
| |
| |
| <p>The Apache Wink runtime first sorts the resources based on their priority and then based on the JAX-RS specification, thus if two resources have the same path, the one with higher priority is invoked.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-ProviderPriorities"></a>Provider Priorities</h3> |
| |
| <p>JAX-RS requires that application-provided providers be used in preference to implementation pre-packaged providers. Apache Wink extends this requirement by allowing applications to specify a priority for providers.</p> |
| |
| <p>The Apache Wink runtime initially sorts the matching providers according to the JAX-RS specification, and uses the priority as the last sorting key for providers of equal standing.<br/> |
| If two providers have the same priority, the order in which they are registered determines their priority such that the latest addition receives the highest priority.<br/> |
| In order to meet the JAX-RS requirements, the pre-packages providers are registered using a priority of 0.1.</p> |
| |
| <h4><a name="5.1RegistrationandConfiguration-PropertiesTable"></a>Properties Table</h4> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Property Name <br clear="all" /> </th> |
| <th class='confluenceTh'> Description <br clear="all" /> </th> |
| <th class='confluenceTh'> Default Value <br clear="all" /> </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.http.uri <br clear="all" /> </td> |
| <td class='confluenceTd'> URI that is used by the Link Builders in case of HTTP <br clear="all" /> </td> |
| <td class='confluenceTd'> Use the URI from the request <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.https.uri <br clear="all" /> </td> |
| <td class='confluenceTd'> URI used by the Link Builders in case of HTTPS <br clear="all" /> </td> |
| <td class='confluenceTd'> Use the URI from the request <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.context.uri <br clear="all" /> </td> |
| <td class='confluenceTd'> Context path used by the Link Builders <br clear="all" /> </td> |
| <td class='confluenceTd'> Use the context path from the request <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.defaultUrisRelative <br clear="all" /> </td> |
| <td class='confluenceTd'> Indicates if URIs generated by the Link Builders are absolute or relative, valid values: true or false <br clear="all" /> </td> |
| <td class='confluenceTd'> true - links are relative <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.addAltParam <br clear="all" /> </td> |
| <td class='confluenceTd'> Indicates if the "alt" query parameter should be added to URIs generated by the Link Builders. Valid values are: true, false <br clear="all" /> </td> |
| <td class='confluenceTd'> true - add the alt query parameter <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.search<br clear="all" /> |
| PolicyContinuedSearch <br clear="all" /> </td> |
| <td class='confluenceTd'> Indicates if continues search is enabled. Valid values: true, false <br clear="all" /> </td> |
| <td class='confluenceTd'> true - continued search is enabled <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.rootResource <br clear="all" /> </td> |
| <td class='confluenceTd'> Indicates if a root resource with Service Document generation capabilities should be added. <br clear="all" /> |
| Valid values are: none, atom, atom+html <br clear="all" /> </td> |
| <td class='confluenceTd'> atom+html --atom and html Service Document generation capabilities <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.serviceDocumentCssPath <br clear="all" /> </td> |
| <td class='confluenceTd'> Defines path to a css file that is used in the html Service Document generation. Relevant only if html Service Document is defined <br clear="all" /> </td> |
| <td class='confluenceTd'> No css file defined <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.handlersFactoryClass <br clear="all" /> </td> |
| <td class='confluenceTd'> Defines a org.apache.wink.server<br clear="all" /> |
| .handlers.HandlersFactory class that defines user handlers <br clear="all" /> </td> |
| <td class='confluenceTd'> No user handlers defined <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.mediaType<br clear="all" /> |
| MapperFactoryClass <br clear="all" /> </td> |
| <td class='confluenceTd'> Defines a org.apache.wink.server.handlers<br clear="all" /> |
| .MediaTypeMapperFactory class that defines media type mappers <br clear="all" /> </td> |
| <td class='confluenceTd'> No media type mappers defined <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> wink.loadApplications <br clear="all" /> </td> |
| <td class='confluenceTd'> Loads providers defined in a wink-application file found by the runtime <br clear="all" /> </td> |
| <td class='confluenceTd'> True, automatically load all wink-application specified classes <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h3><a name="5.1RegistrationandConfiguration-CustomPropertiesFileDefinition"></a>Custom Properties File Definition</h3> |
| |
| <p>In order to provide a custom properties file, the application should define the propertiesLocation init-param in the Apache Wink Servlet definition.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml"># Providers
|
| <span class="code-tag"><servlet></span>
|
| <span class="code-tag"><servlet-name></span>restSdkService<span class="code-tag"></servlet-name></span>
|
| <span class="code-tag"><servlet-class></span>
|
| org.apache.wink.server.internal.servlet.RestServlet
|
| <span class="code-tag"></servlet-class></span>
|
| <span class="code-tag"><init-param></span>
|
| <span class="code-tag"><param-name></span>propertiesLocation<span class="code-tag"></param-name></span>
|
| <span class="code-tag"><param-value></span>/WEB-INF/configuration.properties<span class="code-tag"></param-value></span>
|
| <span class="code-tag"></init-param></span>
|
| <span class="code-tag"><init-param></span>
|
| <span class="code-tag"><param-name></span>winkApplicationConfigLocation<span class="code-tag"></param-name></span>
|
| <span class="code-tag"><param-value></span>/WEB-INF/application<span class="code-tag"></param-value></span>
|
| <span class="code-tag"></init-param></span>
|
| <span class="code-tag"><load-on-startup></span>0<span class="code-tag"></load-on-startup></span>
|
| <span class="code-tag"></servlet></span>
|
| </pre> |
| </div></div> |
| |
| <h2><a name="5.1RegistrationandConfiguration-Runtime"></a>Runtime</h2> |
| |
| <p>RegistrationApache Wink provides several APIs for Runtime Registration. The APIs appear in the org.apache.wink.server.utils.RegistrationUtils class. The most important method is the one that registers an instance of the javax.ws.rs.core.Application class</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-xml"># Providers
|
| static void registerApplication(Application application, ServletContext servletContext)
|
| </pre> |
| </div></div> |
| <div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Double Registration</b><br />Registration is ignored and a warning is printed to the log if the instance was previously registered</td></tr></table></div> |
| |
| <h2><a name="5.1RegistrationandConfiguration-MediaTypeMapping"></a>Media-Type Mapping</h2> |
| |
| <p>It is sometimes necessary to override the Content-Type response header based on the client user agent. For example, the Firefox browser cannot handle the application/atom+xml media type for Atom content, unless it is defined as a text/xml.</p> |
| |
| <p>Apache Wink provides a set of predefined Media-Type mappings for use in such cases by supplying the MediaTypeMapper class. Applications may extend or override the MediaTypeMapper class to define additional mappings.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-CustomizingMappings"></a>Customizing Mappings</h3> |
| |
| <p>In order to customize these mappings the application should create a instance of a org.apache.wink.server.handlers.MediaTypeMapperFactory class and set it in a customized Wink properties file.</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 />Refer to section <a href="" title="5.1 Registration and Configuration">5.1 Registration and Configuration</a> for more information on Customizing the Default Properties Configuration.</td></tr></table></div> |
| |
| <h2><a name="5.1RegistrationandConfiguration-"></a></h2> |
| |
| |
| <h2><a name="5.1RegistrationandConfiguration-AlternativeShortcuts"></a>Alternative Shortcuts</h2> |
| |
| <p>Clients specify the requested media type by setting the Http Accept header. Apache Wink provides an alternate method for specifying the requested media type via use of the "alt" request parameter. This functionality is useful for situation where the client has little affect on the accept header, for example when requesting a resource using a browser.</p> |
| |
| <p>For example, a request to /entry?alt=application/xml specifies that the requested response media type is application/xml. Apache Wink provides a shortcut mechanism for specifying the media type of the alt query parameter and provides a predefined set of shortcuts for common media types.</p> |
| |
| <h3><a name="5.1RegistrationandConfiguration-PredefinedShortcuts"></a>Predefined Shortcuts</h3> |
| |
| <table class='confluenceTable'><tbody> |
| <tr> |
| <th class='confluenceTh'> Shortcut <br clear="all" /> </th> |
| <th class='confluenceTh'> Media Type <br clear="all" /> </th> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> json <br clear="all" /> </td> |
| <td class='confluenceTd'> text/javascript <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> atom <br clear="all" /> </td> |
| <td class='confluenceTd'> application/atom+xml <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> xml <br clear="all" /> </td> |
| <td class='confluenceTd'> application/xml <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> text <br clear="all" /> </td> |
| <td class='confluenceTd'> text/plain <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> html <br clear="all" /> </td> |
| <td class='confluenceTd'> text/html <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> csv <br clear="all" /> </td> |
| <td class='confluenceTd'> text/csv <br clear="all" /> </td> |
| </tr> |
| <tr> |
| <td class='confluenceTd'> opensearch <br clear="all" /> </td> |
| <td class='confluenceTd'> application/opensearchdescription+xml <br clear="all" /> </td> |
| </tr> |
| </tbody></table> |
| |
| <h3><a name="5.1RegistrationandConfiguration-CustomizingShortcuts"></a>Customizing Shortcuts</h3> |
| |
| <p>The shortcuts table can be customized by overriding the deployment configuration class.</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 />Refer to section <a href="2 Apache Wink Building Blocks.html#2ApacheWinkBuildingBlocks-DeploymentConfiguration">2 Apache Wink Building Blocks</a> for more information on Customizing the Default Deployment Configuration.</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> |
