com.google.inject.servlet Documentation Differences
This file contains all the changes in documentation in the package com.google.inject.servlet as colored differences.
Deletions are shown like this, and
additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences.
If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here.
Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.
Class GuiceFilter
Apply this filter in web.xml above all other filters (typically), to all requests where you plan
to use servlet scopes. This is also needed in order to dispatch requests to injectable filters
and servlets:
<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 filter must appear before every filter that makes use of Guice injection or servlet
scopesservlet scopes
functionality. Typically, you will only register this filter in web.xml and register
register any otherother
filters (and servlets) using a ServletModule.
@author crazybob@google.com (Bob Lee)
@author dhanji@gmail.com (Dhanji R. Prasanna)
Class GuiceServletContextListener
As of Guice 2.0 you can still use (your subclasses of) {@code GuiceServletContextListener}
classclass
as a logical place to create and configure your injector. This will ensure the injector
injector isis
created when the web application is deployed.
@author Kevin Bourrillion (kevinb@google.com)
@since 2.0
Class GuiceServletContextListener, Injector getInjector()
Override this method to create (or otherwise obtain a reference to) your
your injector.
Class InstanceFilterBinding
A binding to a single instance of a filter.
@author sameb@google.com
@since 3.0
Class InstanceServletBinding
A binding to a single instance of a servlet.
@author sameb@google.com
@since 3.0
Class LinkedFilterBinding
A linked binding to a filter.
@author sameb@google.com
@since 3.0
Class LinkedServletBinding
A linked binding to a servlet.
@author sameb@google.com
@since 3.0
Class RequestParameters
Apply this to field or parameters of type {@code Map}
when you want the HTTPHTTP
request parameter map to be injected.
@author crazybob@google.com (Bob Lee)
Class RequestScoper, CloseableScope open()
Opens up the request scope until the returned object is closed.
Implementations should ensureensure
(e.g. by blocking) that multiple threads
threads cannot open the same request scope concurrently. It isis
allowable to open
open the same request scope on the same thread, as long as open/close calls are
correctly nested.
Class ScopingOnly
Annotates a GuiceFilter that provides scope functionality, but
but doesn't dispatch to ServletModule bound servlets or filters.
@author iqshum@google.com (Isaac Shum)
@since 4.0
Class ServletModule
Configures the servlet scopes and creates bindings for the servlet API
API objects so you can injectinject
the request, response, session, etc.
You should subclass this module to register servlets and
and filters in the .configureServlets() method.
@author crazybob@google.com (Bob Lee)
@author dhanji@gmail.com (Dhanji R. Prasanna)
Class ServletModule, void configureServlets()
Servlet Mapping EDSL
Part of the EDSL builder language for configuring servlets
servlets and filters with guice-servlet.
Think of this as an in-code replacement for web.xml.
Filters and servlets are configured herehere
using simple java method calls. Here is a typical
typical example of registering a filter when creatingcreating
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
in youryour
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
will bebe
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
url "{@codecode
/my/file.js}" (after it runs through the matching filters) will first
first be compared against thethe
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
These two mappingmapping
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
alsois 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
html
- http://www.google.com/content/ajax/
index
index
- http://www.google.com/it/is_totally_
ajaxian
ajaxian
Initialization Parameters
Servlets (and filters) allow you to pass in init params
params using the {@code } tag inin
web.xml. You can similarly pass in parameters to
to Servlets and filters registered inin
Guice-servlet using a java.util.Map of parameter
parameter name/value pairs. For example, toto
initialize {@code MyServlet} with two parameters
parameters ({@code name="Dhanji", site="google.com"}) youyou
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
hide implementations withwith
package-local visbility and expose them using
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
this filter'ss
implementation:
bind(Filter.class).annotatedWith(Fave.class).to(MyFilterImpl.class);
See 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
different modules.
This is essential if you want to package and offer drop-in Guice plugins that
that provide servletservlet
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
oforder 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
mapped toto
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
thewhich the
modules are installed:
install(new WebServiceModule());
install(new RpcModule());
In the case shown above {@code WebServiceFilter} will run first.
@since 2.0
Class ServletModule, ServletContext getServletContext()
This method only works if you are using the GuiceServletContextListener to
createto create
your injector. Otherwise, it returns null.
@return The current servlet context.
@since 3.0
Class ServletModuleBinding
A binding created by ServletModule.
@author sameb@google.com (Sam Berlin)
@since 3.0
Class ServletModuleTargetVisitor
A visitor for the servlet extension.
If your BindingTargetVisitor implements this interface, bindings created by using
ServletModule will be visited through this interface.
@since 3.0
@author sameb@google.com (Sam Berlin)
Class ServletModuleTargetVisitor, V visit(InstanceFilterBinding)
Visits a filter binding created by ServletModule.filter where
where FilterKeyBindingBuilder.through is called with a Filter.
If multiple patterns were specified, this will be called multiple times.
Class ServletModuleTargetVisitor, V visit(InstanceServletBinding)
Visits a servlet binding created by ServletModule.serve where
ServletKeyBindingBuilder.with, is called with an HttpServlet.
If multiple patterns were specified, this will be called multiple times.
Class ServletModuleTargetVisitor, V visit(LinkedFilterBinding)
Visits a filter binding created by ServletModule.filter, where
where FilterKeyBindingBuilder.through is called with a Class or Key.
If multiple patterns were specified, this will be called multiple times.
Class ServletModuleTargetVisitor, V visit(LinkedServletBinding)
Visits a servlet binding created by ServletModule.serve where
where ServletKeyBindingBuilder.with, is called with a Class or Key.
If multiple patterns were specified, this will be called multiple times.
Class ServletScopes, Callable<T> continueRequest(Callable<T>, Map<Key<?>, Object>)
Wraps the given callable in a contextual callable that "continues" the
the HTTP request in anotheranother
thread. This acts as a way of transporting
transporting request context data from the request processingprocessing
thread to to worker
worker threads.
There are some limitations:
- Derived objects (i.e. anything marked @RequestScoped will not
be
be transported.
- State changes to the HttpServletRequest after this method is
called
called will not be seen in thethe
continued thread.
- Only the HttpServletRequest, ServletContext and request
parameter
parameter map are available in thethe
continued thread. The response and session
session are not available.
The returned callable will throw a ScopingException when called
called if the HTTP requestrequest
scope is still active on the current thread.
@param callable code to be executed in another thread, which depends on
on the request scope.
@param seedMap the initial set of scoped instances for Guice to seed the
the request scope with. To
To seed a key with null, use {@code null} as
as the value.
@return a callable that will invoke the given callable, making the request
request context available to
context available to it.
@throws OutOfScopeException if this method is called from a non-request
request thread, or if thethe
request has completed.
@since 3.0
@deprecated You probably want to use {@code transferRequest} instead
Class ServletScopes, boolean isRequestScoped(Binding<?>)
Returns true if {@code binding} is request-scoped. If the binding is a
a linked key binding and
and belongs to an injector (i. e. itit
was retrieved via
via Injector.getBinding()), then this method will
also return true if the target binding is request-scoped.
@since 4.0
Class ServletScopes, Callable<T> scopeRequest(Callable<T>, Map<Key<?>, Object>)
Scopes the given callable inside a request scope. This is not the same
same as the HTTP requestrequest
scope, but is used if no HTTP request scope is in
in progress. In this way, keys can be scopedscoped
as @RequestScoped and exist
exist in non-HTTP requests (for example: RPC requests) as well as in HTTP
request threads.
The returned callable will throw a ScopingException when called
called if there is aa
request scope already active on the current thread.
@param callable code to be executed which depends on the request scope.
Typically in another
Typically in another thread, but not necessarily so.
@param seedMap the initial set of scoped instances for Guice to seed the
the request scope with. To
To seed a key with null, use {@code null} as
as the value.
@return a callable that when called will run inside the a request scope
scope that exposes the
that exposes the instances in the {@code seedMap} as scoped keys.
@since 3.0
Class ServletScopes, RequestScoper scopeRequest(Map<Key<?>, Object>)
Returns an object that will apply request scope to a block of code. This is
is not the same as thethe
HTTP request scope, but is used if no HTTP request
request scope is in progress. In this way, keys cancan
be scoped as @RequestScoped and
and exist in non-HTTP requests (for example: RPC requests) as wellwell
as in HTTP
HTTP request threads.
The returned object will throw a ScopingException when opened
opened if there is a requestrequest
scope already active on the current thread.
@param seedMap the initial set of scoped instances for Guice to seed the
the request scope with. To
To seed a key with null, use {@code null} as
as the value.
@return an object that when opened will initiate the request scope
@since 4.1
Class ServletScopes, RequestScoper transferRequest()
Returns an object that "transfers" the request to another thread. This acts
acts as a way ofof
transporting request context data from the current thread to a
a future thread. The transferredtransferred
scope is the one active for the thread that
that calls this method. A later call to {@code open()}
activates the transferred
transferred the scope, including propagating any objects scoped at that time.
As opposed to .continueRequest, this method propagates all
all existing scoped objects.
The primary use case is in server implementations
implementations where you can detach the request processingprocessing
thread while waiting for data,
and reattach to a different thread to finish processing at aa
later time.
Because request-scoped objects are not typically thread-safe, it is
is important to avoidavoid
applying the same request scope concurrently. The
The returned Scoper will block on open until thethe
current thread has released
released the request scope.
@return an object that when opened will initiate the request scope
@throws OutOfScopeException if this method is called from a non-request
request thread, or if thethe
request has completed.
@since 4.1
Class ServletScopes, Callable<T> transferRequest(Callable<T>)
Wraps the given callable in a contextual callable that "transfers" the
the request to anotheranother
thread. This acts as a way of transporting
transporting request context data from the current thread to aa
future thread.
As opposed to .continueRequest, this method propagates all
all existing scoped objects.
The primary use case is in server implementations
implementations where you can detach the request processingprocessing
thread while waiting for data,
and reattach to a different thread to finish processing at aa
later time.
Because request-scoped objects are not typically thread-safe, the
the callable returned by thisthis
method must not be run on a different thread
thread until the current request scope has terminated.
The returned callable will
will block until the current thread has released the request scope.
@param callable code to be executed in another thread, which depends on
on the request scope.
@return a callable that will invoke the given callable, making the request
request context available to
context available to it.
@throws OutOfScopeException if this method is called from a non-request
request thread, or if thethe
request has completed.
@since 4.0
Class UriPatternType
An enumeration of the available URI-pattern matching styles
styles
@since 3.0