com.google.inject.servlet.ServletModule Maven / Gradle / Ivy
/**
* Copyright (C) 2010 Mycila ([email protected])
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.inject.servlet;
import com.google.common.base.Preconditions;
import com.google.common.collect.Lists;
import com.google.inject.AbstractModule;
import com.google.inject.Key;
import javax.servlet.Filter;
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServlet;
import java.util.Map;
/**
* Configures the servlet scopes and creates bindings for the servlet API
* objects so you can inject the request, response, session, etc.
*
*
* You should subclass this module to register servlets and
* filters in the {@link #configureServlets()} method.
*
* @author [email protected] (Bob Lee)
* @author [email protected] (Dhanji R. Prasanna)
*/
public class ServletModule extends AbstractModule {
@Override
protected final void configure() {
Preconditions.checkState(filtersModuleBuilder == null, "Re-entry is not allowed.");
Preconditions.checkState(servletsModuleBuilder == null, "Re-entry is not allowed.");
filtersModuleBuilder = new FiltersModuleBuilder();
servletsModuleBuilder = new ServletsModuleBuilder();
try {
// Install common bindings (skipped if already installed).
install(new InternalServletModule());
// Install local filter and servlet bindings.
configureServlets();
install(filtersModuleBuilder);
install(servletsModuleBuilder);
} finally {
filtersModuleBuilder = null;
servletsModuleBuilder = null;
}
}
/**
* Servlet Mapping EDSL
*
* Part of the EDSL builder language for configuring servlets
* and filters with guice-servlet. Think of this as an in-code replacement for web.xml.
* Filters and servlets are configured here using simple java method calls. Here is a typical
* example of registering a filter when creating your Guice injector:
*
*
* Guice.createInjector(..., new ServletModule() {
*
* {@literal @}Override
* protected void configureServlets() {
* serve("*.html").with(MyServlet.class)
* }
* }
*
*
* This registers a servlet (subclass of {@code HttpServlet}) called {@code MyServlet} to service
* any web pages ending in {@code .html}. You can also use a path-style syntax to register
* servlets:
*
*
* serve("/my/*").with(MyServlet.class)
*
*
* Every servlet (or filter) is required to be a singleton. If you cannot annotate the class
* directly, you should add a separate {@code bind(..).in(Singleton.class)} rule elsewhere in
* your module. Mapping a servlet that is bound under any other scope is an error.
*
*
* Dispatch Order
* You are free to register as many servlets and filters as you like this way. They will
* be compared and dispatched in the order in which the filter methods are called:
*
*
*
* Guice.createInjector(..., new ServletModule() {
*
* {@literal @}Override
* protected void configureServlets() {
* filter("/*").through(MyFilter.class);
* filter("*.css").through(MyCssFilter.class);
* filter("*.jpg").through(new MyJpgFilter());
* // etc..
*
* serve("*.html").with(MyServlet.class);
* serve("/my/*").with(MyServlet.class);
* serve("*.jpg").with(new MyServlet());
* // etc..
* }
* }
*
* This will traverse down the list of rules in lexical order. For example, a url
* "{@code /my/file.js}" (after it runs through the matching filters) will first
* be compared against the servlet mapping:
*
*
* serve("*.html").with(MyServlet.class);
*
* And failing that, it will descend to the next servlet mapping:
*
*
* serve("/my/*").with(MyServlet.class);
*
*
* Since this rule matches, Guice Servlet will dispatch to {@code MyServlet}. These
* two mapping rules can also be written in more compact form using varargs syntax:
*
*
* serve("*.html", "/my/*").with(MyServlet.class);
*
*
* This way you can map several URI patterns to the same servlet. A similar syntax is
* also available for filter mappings.
*
*
* Regular Expressions
* You can also map servlets (or filters) to URIs using regular expressions:
*
* serveRegex("(.)*ajax(.)*").with(MyAjaxServlet.class)
*
*
* This will map any URI containing the text "ajax" in it to {@code MyAjaxServlet}. Such as:
*
* - http://www.google.com/ajax.html
* - http://www.google.com/content/ajax/index
* - http://www.google.com/it/is_totally_ajaxian
*
*
*
* Initialization Parameters
*
* Servlets (and filters) allow you to pass in init params
* using the {@code } tag in web.xml. You can similarly pass in parameters to
* Servlets and filters registered in Guice-servlet using a {@link java.util.Map} of parameter
* name/value pairs. For example, to initialize {@code MyServlet} with two parameters
* ({@code name="Dhanji", site="google.com"}) you could write:
*
*
* Map<String, String> params = new HashMap<String, String>();
* params.put("name", "Dhanji");
* params.put("site", "google.com");
*
* ...
* serve("/*").with(MyServlet.class, params)
*
*
*
* Binding Keys
*
* You can also bind keys rather than classes. This lets you hide
* implementations with package-local visbility and expose them using
* only a Guice module and an annotation:
*
*
* ...
* filter("/*").through(Key.get(Filter.class, Fave.class));
*
*
* Where {@code Filter.class} refers to the Servlet API interface and {@code Fave.class} is a
* custom binding annotation. Elsewhere (in one of your own modules) you can bind this
* filter's implementation:
*
*
* bind(Filter.class).annotatedWith(Fave.class).to(MyFilterImpl.class);
*
*
* See {@link com.google.inject.Binder} for more information on binding syntax.
*
*
* Multiple Modules
*
* It is sometimes useful to capture servlet and filter mappings from multiple different
* modules. This is essential if you want to package and offer drop-in Guice plugins that
* provide servlet functionality.
*
*
* Guice Servlet allows you to register several instances of {@code ServletModule} to your
* injector. The order in which these modules are installed determines the dispatch order
* of filters and the precedence order of servlets. For example, if you had two servlet modules,
* {@code RpcModule} and {@code WebServiceModule} and they each contained a filter that mapped
* to the same URI pattern, {@code "/*"}:
*
*
* In {@code RpcModule}:
*
* filter("/*").through(RpcFilter.class);
*
*
* In {@code WebServiceModule}:
*
* filter("/*").through(WebServiceFilter.class);
*
*
* Then the order in which these filters are dispatched is determined by the order in which
* the modules are installed:
*
*
* install(new WebServiceModule());
* install(new RpcModule());
*
*
* In the case shown above {@code WebServiceFilter} will run first.
*
* @since 2.0
*/
protected void configureServlets() {
}
private FiltersModuleBuilder filtersModuleBuilder;
private ServletsModuleBuilder servletsModuleBuilder;
/**
* @param urlPattern Any Servlet-style pattern. examples: /*, /html/*, *.html, etc.
* @since 2.0
*/
protected final FilterKeyBindingBuilder filter(String urlPattern, String... morePatterns) {
return filtersModuleBuilder.filter(Lists.asList(urlPattern, morePatterns));
}
/**
* @param regex Any Java-style regular expression.
* @since 2.0
*/
protected final FilterKeyBindingBuilder filterRegex(String regex, String... regexes) {
return filtersModuleBuilder.filterRegex(Lists.asList(regex, regexes));
}
/**
* @param urlPattern Any Servlet-style pattern. examples: /*, /html/*, *.html, etc.
* @since 2.0
*/
protected final ServletKeyBindingBuilder serve(String urlPattern, String... morePatterns) {
return servletsModuleBuilder.serve(Lists.asList(urlPattern, morePatterns));
}
/**
* @param regex Any Java-style regular expression.
* @since 2.0
*/
protected final ServletKeyBindingBuilder serveRegex(String regex, String... regexes) {
return servletsModuleBuilder.serveRegex(Lists.asList(regex, regexes));
}
/**
* This method only works if you are using the {@linkplain GuiceServletContextListener} to
* create your injector. Otherwise, it returns null.
*
* @return The current servlet context.
* @since 3.0
*/
protected final ServletContext getServletContext() {
return GuiceFilter.getServletContext();
}
/**
* See the EDSL examples at {@link ServletModule#configureServlets()}
*
* @since 2.0
*/
public static interface FilterKeyBindingBuilder {
void through(Class filterKey);
void through(Key filterKey);
/**
* @since 3.0
*/
void through(Filter filter);
void through(Class filterKey, Map initParams);
void through(Key filterKey, Map initParams);
/**
* @since 3.0
*/
void through(Filter filter, Map initParams);
}
/**
* See the EDSL examples at {@link ServletModule#configureServlets()}
*
* @since 2.0
*/
public static interface ServletKeyBindingBuilder {
void with(Class servletKey);
void with(Key servletKey);
/**
* @since 3.0
*/
void with(HttpServlet servlet);
void with(Class servletKey, Map initParams);
void with(Key servletKey, Map initParams);
/**
* @since 3.0
*/
void with(HttpServlet servlet, Map initParams);
}
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy