PageRenderTime 58ms CodeModel.GetById 27ms RepoModel.GetById 1ms app.codeStats 0ms

/contribs/jersey-guice/src/main/java/com/sun/jersey/guice/spi/container/servlet/package-info.java

https://github.com/imyousuf/jersey
Java | 188 lines | 1 code | 1 blank | 186 comment | 0 complexity | 7969eebf310d012cad7485949d2e4bab MD5 | raw file
Possible License(s): Apache-2.0, BSD-3-Clause-No-Nuclear-License-2014, GPL-2.0
  1. /*
  2. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  3. *
  4. * Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved.
  5. *
  6. * The contents of this file are subject to the terms of either the GNU
  7. * General Public License Version 2 only ("GPL") or the Common Development
  8. * and Distribution License("CDDL") (collectively, the "License"). You
  9. * may not use this file except in compliance with the License. You can
  10. * obtain a copy of the License at
  11. * http://glassfish.java.net/public/CDDL+GPL_1_1.html
  12. * or packager/legal/LICENSE.txt. See the License for the specific
  13. * language governing permissions and limitations under the License.
  14. *
  15. * When distributing the software, include this License Header Notice in each
  16. * file and include the License file at packager/legal/LICENSE.txt.
  17. *
  18. * GPL Classpath Exception:
  19. * Oracle designates this particular file as subject to the "Classpath"
  20. * exception as provided by Oracle in the GPL Version 2 section of the License
  21. * file that accompanied this code.
  22. *
  23. * Modifications:
  24. * If applicable, add the following below the License Header, with the fields
  25. * enclosed by brackets [] replaced by your own identifying information:
  26. * "Portions Copyright [year] [name of copyright owner]"
  27. *
  28. * Contributor(s):
  29. * If you wish your version of this file to be governed by only the CDDL or
  30. * only the GPL Version 2, indicate your decision by adding "[Contributor]
  31. * elects to include this software in this distribution under the [CDDL or GPL
  32. * Version 2] license." If you don't indicate a single choice of license, a
  33. * recipient has the option to distribute your version of this file under
  34. * either the CDDL, the GPL Version 2 or to extend the choice of license to
  35. * its licensees as provided above. However, if you add GPL Version 2 code
  36. * and therefore, elected the GPL Version 2 license, then the option applies
  37. * only if the new code is made subject to such option by the copyright
  38. * holder.
  39. */
  40. /**
  41. * Provides support for Guice-based Web applications.
  42. * <p>
  43. * Guice support is enabled by referencing the Guice filter
  44. * {@link com.google.inject.servlet.GuiceFilter} and an application
  45. * specific {@link javax.servlet.ServletContextListener} that extends from
  46. * {@link com.google.inject.servlet.GuiceServletContextListener} in the web.xml.
  47. * For example, the web.xml may be as follows:
  48. * <blockquote><pre>
  49. * &lt;web-app&gt;
  50. * &lt;listener&gt;
  51. * &lt;listener-class&gt;foo.MyGuiceConfig&lt;/listener-class&gt;
  52. * &lt;/listener&gt;
  53. * &lt;filter&gt;
  54. * &lt;filter-name&gt;Guice Filter&lt;/filter-name&gt;
  55. * &lt;filter-class&gt;com.google.inject.servlet.GuiceFilter&lt;/filter-class&gt;
  56. * &lt;/filter&gt;
  57. * &lt;filter-mapping&gt;
  58. * &lt;filter-name>Guice Filter&lt;/filter-name&gt;
  59. * &lt;url-pattern>/*&lt;/url-pattern&gt;
  60. * &lt;/filter-mapping&gt;
  61. * &lt;/web-app&gt;
  62. * </blockquote></pre>
  63. * and the application specific servlet context listener may be as follows:
  64. * <blockquote><pre>
  65. * package foo;
  66. *
  67. * import com.google.inject.Guice;
  68. * import com.google.inject.Injector;
  69. * import com.google.inject.servlet.GuiceServletContextListener;
  70. * import com.google.inject.servlet.ServletModule;
  71. * import com.sun.jersey.guice.spi.container.servlet.GuiceContainer;
  72. * import com.sun.jersey.guice.JerseyServletModule;
  73. * import foo.GuiceResource;
  74. *
  75. * public class MyGuiceConfig extends GuiceServletContextListener {
  76. *
  77. * &#64;Override
  78. * protected Injector getInjector() {
  79. * return Guice.createInjector(new JerseyServletModule() {
  80. *
  81. * &#64;Override
  82. * protected void configureServlets() {
  83. * bind(GuiceResource.class);
  84. *
  85. * serve("/*").with(GuiceContainer.class);
  86. * }
  87. * });
  88. * }
  89. * }
  90. * </blockquote></pre>
  91. * Notice that one class <code>GuiceResource</code> is bound and the
  92. * {@link com.sun.jersey.guice.spi.container.servlet.GuiceContainer} is
  93. * declared in the <code>serve</code> method. A instance of
  94. * module {@link com.sun.jersey.guice.JerseyServletModule} is created. This
  95. * module extends from {@link com.google.inject.servlet.ServletModule} and
  96. * provides JAX-RS and Jersey bindings.
  97. * <p>
  98. * Instances of
  99. * <code>GuiceResource</code> will be managed according to the scope declared
  100. * using Guice defined scopes. For example the <code>GuiceResource</code>
  101. * could be as follows:
  102. * <blockquote><pre>
  103. * package foo;
  104. *
  105. * import javax.ws.rs.GET;
  106. * import javax.ws.rs.Produces;
  107. * import javax.ws.rs.Path;
  108. * import javax.ws.rs.QueryParam;
  109. * import javax.enterprise.context.RequestScoped;
  110. *
  111. * &#64;Path("bound/perrequest")
  112. * &#64;RequestScoped
  113. * public class GuiceResource {
  114. *
  115. * &#64;QueryParam("x") String x;
  116. *
  117. * &#64;GET
  118. * &#64;Produces("text/plain")
  119. * public String getIt() {
  120. * return "Hello From Guice: " + x;
  121. * }
  122. * }
  123. * </blockquote></pre>
  124. * <p>
  125. * Any root resource or provider classes bound by Guice
  126. * will be automatically registered. It is possible to intermix Guice and
  127. * non-Guice registration of classes by additionally using the normal
  128. * Jersey-based registration mechanisms in the servlet context listener
  129. * implementation. For example:
  130. * <blockquote><pre>
  131. * package foo;
  132. *
  133. * import com.google.inject.Guice;
  134. * import com.google.inject.Injector;
  135. * import com.google.inject.servlet.GuiceServletContextListener;
  136. * import com.google.inject.servlet.ServletModule;
  137. * import com.sun.jersey.api.core.PackagesResourceConfig;
  138. * import com.sun.jersey.guice.spi.container.servlet.GuiceContainer;
  139. * import com.sun.jersey.guice.JerseyServletModule;
  140. * import foo.GuiceResource;
  141. * import java.util.HashMap;
  142. * import java.util.Map;
  143. *
  144. * public class GuiceServletConfig extends GuiceServletContextListener {
  145. *
  146. * &#64;Override
  147. * protected Injector getInjector() {
  148. * return Guice.createInjector(new JerseyServletModule() {
  149. *
  150. * &#64;Override
  151. * protected void configureServlets() {
  152. * bind(GuiceResource.class);
  153. *
  154. * Map&lt;String, String&gt; params = new HashMap&lt;String, String&gt;();
  155. * params.put(PackagesResourceConfig.PROPERTY_PACKAGES, "unbound");
  156. * serve("/*").with(GuiceContainer.class, params);
  157. * }
  158. * });
  159. * }
  160. * }
  161. * </blockquote></pre>
  162. * <p>
  163. * Any root resource or provider classes found in the package <code>unbound</code>
  164. * or sub-packages of will be registered whether they be Guice-bound nor not.
  165. * <p>
  166. * Sometimes it is convenient for developers not to explicitly bind a
  167. * resource or provider, let Guice instantiate, and let Jersey manage
  168. * the life-cycle. This behavior can be enabled for a resource or
  169. * provider class as follows:
  170. * <ol>
  171. * <li>a class constructor is annotated with {@link com.google.inject.Inject};
  172. * <li>the class is not explicitly bound in Guice; and
  173. * <li>the class is registered using a Jersey based registration mechanism,
  174. * for example using package scanning registration.
  175. * </ol>
  176. * <p>
  177. * In other cases it is convenient to let Jersey instantiate and manage
  178. * the life-cycle and let Guice perform injection. This behavior can be
  179. * enabled for a resource or provider class as follows:
  180. * <ol>
  181. * <li>a field or method is annotated with {@link com.google.inject.Inject};
  182. * <li>the class is not explicitly bound in Guice; and
  183. * <li>the class is registered using a Jersey based registration mechanism,
  184. * for example using package scanning registration.
  185. * </ol>
  186. */
  187. package com.sun.jersey.guice.spi.container.servlet;