/contribs/jersey-guice/src/main/java/com/sun/jersey/guice/spi/container/servlet/package-info.java
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/**
42 * Provides support for Guice-based Web applications.
43 * <p>
44 * Guice support is enabled by referencing the Guice filter
45 * {@link com.google.inject.servlet.GuiceFilter} and an application
46 * specific {@link javax.servlet.ServletContextListener} that extends from
47 * {@link com.google.inject.servlet.GuiceServletContextListener} in the web.xml.
48 * For example, the web.xml may be as follows:
49 * <blockquote><pre>
50 * <web-app>
51 * <listener>
52 * <listener-class>foo.MyGuiceConfig</listener-class>
53 * </listener>
54 * <filter>
55 * <filter-name>Guice Filter</filter-name>
56 * <filter-class>com.google.inject.servlet.GuiceFilter</filter-class>
57 * </filter>
58 * <filter-mapping>
59 * <filter-name>Guice Filter</filter-name>
60 * <url-pattern>/*</url-pattern>
61 * </filter-mapping>
62 * </web-app>
63 * </blockquote></pre>
64 * and the application specific servlet context listener may be as follows:
65 * <blockquote><pre>
66 * package foo;
67 *
68 * import com.google.inject.Guice;
69 * import com.google.inject.Injector;
70 * import com.google.inject.servlet.GuiceServletContextListener;
71 * import com.google.inject.servlet.ServletModule;
72 * import com.sun.jersey.guice.spi.container.servlet.GuiceContainer;
73 * import com.sun.jersey.guice.JerseyServletModule;
74 * import foo.GuiceResource;
75 *
76 * public class MyGuiceConfig extends GuiceServletContextListener {
77 *
78 * @Override
79 * protected Injector getInjector() {
80 * return Guice.createInjector(new JerseyServletModule() {
81 *
82 * @Override
83 * protected void configureServlets() {
84 * bind(GuiceResource.class);
85 *
86 * serve("/*").with(GuiceContainer.class);
87 * }
88 * });
89 * }
90 * }
91 * </blockquote></pre>
92 * Notice that one class <code>GuiceResource</code> is bound and the
93 * {@link com.sun.jersey.guice.spi.container.servlet.GuiceContainer} is
94 * declared in the <code>serve</code> method. A instance of
95 * module {@link com.sun.jersey.guice.JerseyServletModule} is created. This
96 * module extends from {@link com.google.inject.servlet.ServletModule} and
97 * provides JAX-RS and Jersey bindings.
98 * <p>
99 * Instances of
100 * <code>GuiceResource</code> will be managed according to the scope declared
101 * using Guice defined scopes. For example the <code>GuiceResource</code>
102 * could be as follows:
103 * <blockquote><pre>
104 * package foo;
105 *
106 * import javax.ws.rs.GET;
107 * import javax.ws.rs.Produces;
108 * import javax.ws.rs.Path;
109 * import javax.ws.rs.QueryParam;
110 * import javax.enterprise.context.RequestScoped;
111 *
112 * @Path("bound/perrequest")
113 * @RequestScoped
114 * public class GuiceResource {
115 *
116 * @QueryParam("x") String x;
117 *
118 * @GET
119 * @Produces("text/plain")
120 * public String getIt() {
121 * return "Hello From Guice: " + x;
122 * }
123 * }
124 * </blockquote></pre>
125 * <p>
126 * Any root resource or provider classes bound by Guice
127 * will be automatically registered. It is possible to intermix Guice and
128 * non-Guice registration of classes by additionally using the normal
129 * Jersey-based registration mechanisms in the servlet context listener
130 * implementation. For example:
131 * <blockquote><pre>
132 * package foo;
133 *
134 * import com.google.inject.Guice;
135 * import com.google.inject.Injector;
136 * import com.google.inject.servlet.GuiceServletContextListener;
137 * import com.google.inject.servlet.ServletModule;
138 * import com.sun.jersey.api.core.PackagesResourceConfig;
139 * import com.sun.jersey.guice.spi.container.servlet.GuiceContainer;
140 * import com.sun.jersey.guice.JerseyServletModule;
141 * import foo.GuiceResource;
142 * import java.util.HashMap;
143 * import java.util.Map;
144 *
145 * public class GuiceServletConfig extends GuiceServletContextListener {
146 *
147 * @Override
148 * protected Injector getInjector() {
149 * return Guice.createInjector(new JerseyServletModule() {
150 *
151 * @Override
152 * protected void configureServlets() {
153 * bind(GuiceResource.class);
154 *
155 * Map<String, String> params = new HashMap<String, String>();
156 * params.put(PackagesResourceConfig.PROPERTY_PACKAGES, "unbound");
157 * serve("/*").with(GuiceContainer.class, params);
158 * }
159 * });
160 * }
161 * }
162 * </blockquote></pre>
163 * <p>
164 * Any root resource or provider classes found in the package <code>unbound</code>
165 * or sub-packages of will be registered whether they be Guice-bound nor not.
166 * <p>
167 * Sometimes it is convenient for developers not to explicitly bind a
168 * resource or provider, let Guice instantiate, and let Jersey manage
169 * the life-cycle. This behavior can be enabled for a resource or
170 * provider class as follows:
171 * <ol>
172 * <li>a class constructor is annotated with {@link com.google.inject.Inject};
173 * <li>the class is not explicitly bound in Guice; and
174 * <li>the class is registered using a Jersey based registration mechanism,
175 * for example using package scanning registration.
176 * </ol>
177 * <p>
178 * In other cases it is convenient to let Jersey instantiate and manage
179 * the life-cycle and let Guice perform injection. This behavior can be
180 * enabled for a resource or provider class as follows:
181 * <ol>
182 * <li>a field or method is annotated with {@link com.google.inject.Inject};
183 * <li>the class is not explicitly bound in Guice; and
184 * <li>the class is registered using a Jersey based registration mechanism,
185 * for example using package scanning registration.
186 * </ol>
187 */
188package com.sun.jersey.guice.spi.container.servlet;