# Jersey Guice Example

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

## Contents of jersey-guice-filter example

  ### web.xml and GuiceServletConfig

  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.

          <listener>
              <listener-class>com.sun.jersey.samples.guice.GuiceServletConfig</listener-class>
          </listener>

  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 "/*". Next, place GuiceFilter after this `</listener>` element in your .web.xml file:

          <filter>
              <filter-name>guiceFilter</filter-name>
              <filter-class>com.google.inject.servlet.GuiceFilter</filter-class>
          </filter>

          <filter-mapping>
              <filter-name>guiceFilter</filter-name>
              <url-pattern>/*</url-pattern>
          </filter-mapping>

  This tells the Servlet Container to re-route all requests through GuiceFilter.

  ### Installing a Servlet Module

  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 `GuiceServletConfig.java` file by overriding `getInjector()` to return our new instance of ServletModule:

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

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

  ### The Binding Language

  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:

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

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

  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:

      public class GuiceServletConfig extends GuiceServletContextListener {

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

  The final class looks like this:

      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);
                  }
              });
          }
      }

  ### Creating resource class

  We have created resource class, `PerRequestResource` which binds path `@Path("bound/perrequest")` to scope using guice `@RequestScoped` as shown in the following code:

      //Create resource class, @Path("bound/perrequest"), using guice @RequestScoped
      @Path("bound/perrequest")
      @RequestScoped
      public class PerRequestResource {

  ### Injecting URI info/query parameter

  We Inject URI info and a query parameter via code:

      //Inject URI info and a query parameter
      @Context UriInfo ui;

      @QueryParam("x") String x;

  ### Singleton Component creation and Injection into resource

  Finally, we create singleton component (see `SingletonComponent.java`) and inject into resource `PerRequestResource` at construction time via code:

      private final SingletonComponent sc;

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

Details here google-guice/ServletModule were copied and applied to our specific example.

The mapping of the URI path space is presented in the following table:

URI path | Resource class | HTTP method | Description
--- | --- | --- | ---
/jersey-guice-filter/bound/perrequest | PerRequestResource | GET | Returns string representing PerRequestResource Context URI info path along with QueryParam and Singleton component's hashcode integer value converted to hex, prefixed by SINGLETON:

## Running the Example

You can run the example using embedded GlassFish as follows:

Build and deploy the project by executing maven from the project directory

> `mvn clean package embedded-glassfish:run`

From a web browser, visit:

> `http://localhost:8080/jersey-guice-filter/bound/perrequest`