README.html | searchcode

/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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--

    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

    Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved.

    The contents of this file are subject to the terms of either the GNU
    General Public License Version 2 only ("GPL") or the Common Development
    and Distribution License("CDDL") (collectively, the "License").  You
    may not use this file except in compliance with the License.  You can
    obtain a copy of the License at
    http://glassfish.java.net/public/CDDL+GPL_1_1.html
    or packager/legal/LICENSE.txt.  See the License for the specific
    language governing permissions and limitations under the License.

    When distributing the software, include this License Header Notice in each
    file and include the License file at packager/legal/LICENSE.txt.

    GPL Classpath Exception:
    Oracle designates this particular file as subject to the "Classpath"
    exception as provided by Oracle in the GPL Version 2 section of the License
    file that accompanied this code.

    Modifications:
    If applicable, add the following below the License Header, with the fields
    enclosed by brackets [] replaced by your own identifying information:
    "Portions Copyright [year] [name of copyright owner]"

    Contributor(s):
    If you wish your version of this file to be governed by only the CDDL or
    only the GPL Version 2, indicate your decision by adding "[Contributor]
    elects to include this software in this distribution under the [CDDL or GPL
    Version 2] license."  If you don't indicate a single choice of license, a
    recipient has the option to distribute your version of this file under
    either the CDDL, the GPL Version 2 or to extend the choice of license to
    its licensees as provided above.  However, if you add GPL Version 2 code
    and therefore, elected the GPL Version 2 license, then the option applies
    only if the new code is made subject to such option by the copyright
    holder.

-->
<html><head><title>Jersey-Guice Example</title></head>

    <!--
     super(new WebAppDescriptor.Builder("com.sun.jersey.samples.guice.resources")
                .contextListenerClass(com.sun.jersey.samples.guice.GuiceServletConfig.class)
                .filterClass(com.google.inject.servlet.GuiceFilter.class)
                .contextPath("jersey-guice-filter")
                .servletPath("/")
                .build());
    -->

    <body>
        <h1>Jersey Guice Example</h1>

        <p>This example demonstrates how to develop Restful WebService sample using Guice Servlet Extensions with a servlet filter.

        <h2>Contents of jersey-guice-filter example</h2>
         <dl>
            <dd>
                <h3>web.xml and GuiceServletConfig </h3>
       You must register both the GuiceFilter and your subclass of GuiceServletContextListener in your application's web.xml file.

       Add the following to web.xml so the servlet container triggers this class when the app is deployed.

       <pre>
    &lt;listener&gt;
        &lt;listener-class&gt;com.sun.jersey.samples.guice.GuiceServletConfig&lt;/listener-class&gt;
    &lt;/listener&gt;
       </pre>

        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>
       
       Next, place GuiceFilter after this <code>&lt;/listener&gt; </code> element in your .web.xml file:
       <pre>
    &lt;filter&gt;
        &lt;filter-name>guiceFilter&lt;/filter-name&gt;
        &lt;filter-class>com.google.inject.servlet.GuiceFilter&lt;/filter-class&gt;
    &lt;/filter&gt;

    &lt;filter-mapping&gt;
        &lt;filter-name>guiceFilter&lt;/filter-name&gt;
        &lt;url-pattern>/*&lt;/url-pattern&gt;
    &lt;/filter-mapping&gt;
       </pre>
This tells the Servlet Container to re-route all requests through GuiceFilter.

<h3>Installing a Servlet Module</h3>
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.
We do this in <code>GuiceServletConfig.java</code> file by overriding <code>getInjector()</code> to return our new instance of ServletModule:

<pre>@Override
protected Injector getInjector() {
        return Guice.createInjector(new ServletModule() {</pre>

You can think of the ServletModule as an in-code replacement for the web.xml deployment descriptor.  

<h3>The Binding Language</h3>
 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:

<pre>@Override
protected void configureServlets() {
    // Bind classes
    bind(PerRequestResource.class);

    serve("/*").with(GuiceContainer.class);
  }
});
</pre>
 The module also provides a place to configure your filters and servlets from. 
 We have chosen to create the injector in our ServletContextListener.
 (Feel free to create the injector from any place you choose).
 A ServletContextListener is a Java servlet component that is triggered as soon
 as a web application is deployed, and before any requests begin to arrive.
 Guice Servlet provides a convenience utility that you can subclass in order
 to register your own ServletContextListeners:

<pre>public class GuiceServletConfig extends GuiceServletContextListener {

@Override
    protected Injector getInjector() {
        return Guice.createInjector(new ServletModule() {
</pre>
The final class looks like this:
<pre>
public class GuiceServletConfig extends GuiceServletContextListener {

    @Override
    protected Injector getInjector() {
        return Guice.createInjector(new ServletModule() {

            @Override
            protected void configureServlets() {
                // Bind classes
                bind(PerRequestResource.class);

                serve("/*").with(GuiceContainer.class);
            }
        });
    }
}
</pre>

<h3>Creating resource class</h3>
       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:
<pre>//Create resource class, @Path("bound/perrequest"), using guice @RequestScoped
@Path("bound/perrequest")
@RequestScoped
public class PerRequestResource {</pre>

<h3>Injecting URI info/query parameter</h3>
We Inject URI info and a query parameter via code:
<pre>//Inject URI info and a query parameter
@Context UriInfo ui;

@QueryParam("x") String x;</pre>

<h3>Singleton Component creation and Injection into resource</h3>
Finally, we create singleton component (see <code>SingletonComponent.java</code>) and inject into resource <code>PerRequestResource</code> at construction time via code:
<pre>private final SingletonComponent sc;

    //Create singleton component and inject into resource at construction
    @Inject
    public PerRequestResource(SingletonComponent sc) {
        this.sc = sc;
    }</pre>
</dd>

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.
       
        </dl>
        <p>The mapping of the URI path space is presented in the following table:</p>
        <table border="1">
            <tbody>
                <tr>
                    <th>URI path</th>
                    <th>Resource class</th>
                    <th>HTTP method</th>
                    <th>Description</th>
                </tr>               
                <tr>
                    <td>/jersey-guice-filter/bound/perrequest</td>
                    <td>PerRequestResource</td>
                    <td>GET</td>
                    <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>
                </tr>               
            </tbody>
        </table>


        <h2>Running the Example</h2>

        <p>You can run the example using embedded GlassFish as follows:</p>

        <p>Build and deploy the project by executing maven from the project directory</p>
        <blockquote><code>mvn clean package embedded-glassfish:run</code></blockquote>

        <p>From a web browser, visit:</p>
        <blockquote><code><a href="http://localhost:8080/jersey-guice-filter/bound/perrequest">http://localhost:8080/jersey-guice-filter/bound/perrequest</a></code>
        </blockquote>
        
    </body>
</html>