PageRenderTime 115ms CodeModel.GetById 35ms RepoModel.GetById 8ms app.codeStats 0ms

/samples/jersey-guice-filter/README.html

https://github.com/imyousuf/jersey
HTML | 204 lines | 122 code | 33 blank | 49 comment | 0 complexity | fa415e2dd9060f555d73718807c54e28 MD5 | raw file
Possible License(s): Apache-2.0, BSD-3-Clause-No-Nuclear-License-2014, GPL-2.0
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <!--
  3. DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  4. Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved.
  5. The contents of this file are subject to the terms of either the GNU
  6. General Public License Version 2 only ("GPL") or the Common Development
  7. and Distribution License("CDDL") (collectively, the "License"). You
  8. may not use this file except in compliance with the License. You can
  9. obtain a copy of the License at
  10. http://glassfish.java.net/public/CDDL+GPL_1_1.html
  11. or packager/legal/LICENSE.txt. See the License for the specific
  12. language governing permissions and limitations under the License.
  13. When distributing the software, include this License Header Notice in each
  14. file and include the License file at packager/legal/LICENSE.txt.
  15. GPL Classpath Exception:
  16. Oracle designates this particular file as subject to the "Classpath"
  17. exception as provided by Oracle in the GPL Version 2 section of the License
  18. file that accompanied this code.
  19. Modifications:
  20. If applicable, add the following below the License Header, with the fields
  21. enclosed by brackets [] replaced by your own identifying information:
  22. "Portions Copyright [year] [name of copyright owner]"
  23. Contributor(s):
  24. If you wish your version of this file to be governed by only the CDDL or
  25. only the GPL Version 2, indicate your decision by adding "[Contributor]
  26. elects to include this software in this distribution under the [CDDL or GPL
  27. Version 2] license." If you don't indicate a single choice of license, a
  28. recipient has the option to distribute your version of this file under
  29. either the CDDL, the GPL Version 2 or to extend the choice of license to
  30. its licensees as provided above. However, if you add GPL Version 2 code
  31. and therefore, elected the GPL Version 2 license, then the option applies
  32. only if the new code is made subject to such option by the copyright
  33. holder.
  34. -->
  35. <html><head><title>Jersey-Guice Example</title></head>
  36. <!--
  37. super(new WebAppDescriptor.Builder("com.sun.jersey.samples.guice.resources")
  38. .contextListenerClass(com.sun.jersey.samples.guice.GuiceServletConfig.class)
  39. .filterClass(com.google.inject.servlet.GuiceFilter.class)
  40. .contextPath("jersey-guice-filter")
  41. .servletPath("/")
  42. .build());
  43. -->
  44. <body>
  45. <h1>Jersey Guice Example</h1>
  46. <p>This example demonstrates how to develop Restful WebService sample using Guice Servlet Extensions with a servlet filter.
  47. <h2>Contents of jersey-guice-filter example</h2>
  48. <dl>
  49. <dd>
  50. <h3>web.xml and GuiceServletConfig </h3>
  51. You must register both the GuiceFilter and your subclass of GuiceServletContextListener in your application's web.xml file.
  52. Add the following to web.xml so the servlet container triggers this class when the app is deployed.
  53. <pre>
  54. &lt;listener&gt;
  55. &lt;listener-class&gt;com.sun.jersey.samples.guice.GuiceServletConfig&lt;/listener-class&gt;
  56. &lt;/listener&gt;
  57. </pre>
  58. GuiceServletConfig is class that extends GuiceServletContextListener and overrides the getInjector() method to return a Guice injector which has it's configureServlets method overridden to filter all request "/*".</p>
  59. Next, place GuiceFilter after this <code>&lt;/listener&gt; </code> element in your .web.xml file:
  60. <pre>
  61. &lt;filter&gt;
  62. &lt;filter-name>guiceFilter&lt;/filter-name&gt;
  63. &lt;filter-class>com.google.inject.servlet.GuiceFilter&lt;/filter-class&gt;
  64. &lt;/filter&gt;
  65. &lt;filter-mapping&gt;
  66. &lt;filter-name>guiceFilter&lt;/filter-name&gt;
  67. &lt;url-pattern>/*&lt;/url-pattern&gt;
  68. &lt;/filter-mapping&gt;
  69. </pre>
  70. This tells the Servlet Container to re-route all requests through GuiceFilter.
  71. <h3>Installing a Servlet Module</h3>
  72. Now that you have GuiceFilter configured, Guice Servlet is set up. Next, you will need to install an instance of ServletModule in order really use Guice Servlet.
  73. We do this in <code>GuiceServletConfig.java</code> file by overriding <code>getInjector()</code> to return our new instance of ServletModule:
  74. <pre>@Override
  75. protected Injector getInjector() {
  76. return Guice.createInjector(new ServletModule() {</pre>
  77. You can think of the ServletModule as an in-code replacement for the web.xml deployment descriptor.
  78. <h3>The Binding Language</h3>
  79. Filters and servlets are configured here in ServletModule using normal Java method calls. This module sets up the request and session scopes. Here we are registering a servlet during creation of Guice injector:
  80. <pre>@Override
  81. protected void configureServlets() {
  82. // Bind classes
  83. bind(PerRequestResource.class);
  84. serve("/*").with(GuiceContainer.class);
  85. }
  86. });
  87. </pre>
  88. The module also provides a place to configure your filters and servlets from.
  89. We have chosen to create the injector in our ServletContextListener.
  90. (Feel free to create the injector from any place you choose).
  91. A ServletContextListener is a Java servlet component that is triggered as soon
  92. as a web application is deployed, and before any requests begin to arrive.
  93. Guice Servlet provides a convenience utility that you can subclass in order
  94. to register your own ServletContextListeners:
  95. <pre>public class GuiceServletConfig extends GuiceServletContextListener {
  96. @Override
  97. protected Injector getInjector() {
  98. return Guice.createInjector(new ServletModule() {
  99. </pre>
  100. The final class looks like this:
  101. <pre>
  102. public class GuiceServletConfig extends GuiceServletContextListener {
  103. @Override
  104. protected Injector getInjector() {
  105. return Guice.createInjector(new ServletModule() {
  106. @Override
  107. protected void configureServlets() {
  108. // Bind classes
  109. bind(PerRequestResource.class);
  110. serve("/*").with(GuiceContainer.class);
  111. }
  112. });
  113. }
  114. }
  115. </pre>
  116. <h3>Creating resource class</h3>
  117. We have created resource class, <code>PerRequestResource</code> which binds path <code>@Path("bound/perrequest")</code> to scope using guice <code>@RequestScoped</code> as shown in the following code:
  118. <pre>//Create resource class, @Path("bound/perrequest"), using guice @RequestScoped
  119. @Path("bound/perrequest")
  120. @RequestScoped
  121. public class PerRequestResource {</pre>
  122. <h3>Injecting URI info/query parameter</h3>
  123. We Inject URI info and a query parameter via code:
  124. <pre>//Inject URI info and a query parameter
  125. @Context UriInfo ui;
  126. @QueryParam("x") String x;</pre>
  127. <h3>Singleton Component creation and Injection into resource</h3>
  128. Finally, we create singleton component (see <code>SingletonComponent.java</code>) and inject into resource <code>PerRequestResource</code> at construction time via code:
  129. <pre>private final SingletonComponent sc;
  130. //Create singleton component and inject into resource at construction
  131. @Inject
  132. public PerRequestResource(SingletonComponent sc) {
  133. this.sc = sc;
  134. }</pre>
  135. </dd>
  136. Details here <a href="http://code.google.com/p/google-guice/wiki/ServletModule">google-guice/ServletModule</a> were copied and applied to our specific example.
  137. </dl>
  138. <p>The mapping of the URI path space is presented in the following table:</p>
  139. <table border="1">
  140. <tbody>
  141. <tr>
  142. <th>URI path</th>
  143. <th>Resource class</th>
  144. <th>HTTP method</th>
  145. <th>Description</th>
  146. </tr>
  147. <tr>
  148. <td>/jersey-guice-filter/bound/perrequest</td>
  149. <td>PerRequestResource</td>
  150. <td>GET</td>
  151. <td>Returns string representing PerRequestResource Context URI info path along with QueryParam and Singleton component's hashcode integer value converted to hex, prefixed by SINGLETON: </td>
  152. </tr>
  153. </tbody>
  154. </table>
  155. <h2>Running the Example</h2>
  156. <p>You can run the example using embedded GlassFish as follows:</p>
  157. <p>Build and deploy the project by executing maven from the project directory</p>
  158. <blockquote><code>mvn clean package embedded-glassfish:run</code></blockquote>
  159. <p>From a web browser, visit:</p>
  160. <blockquote><code><a href="http://localhost:8080/jersey-guice-filter/bound/perrequest">http://localhost:8080/jersey-guice-filter/bound/perrequest</a></code>
  161. </blockquote>
  162. </body>
  163. </html>