Google Git
Sign in
android / platform / external / guice / ada2f98ef48dc9740dc5e6922743d6f7a1a5cc2c / . / latest-api-diffs / changes / docdiffs_com.google.inject.html
blob: ab4db7eecd8ed234a2a50e8ef47d2a54b286aaa9 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN""http://www.w3.org/TR/REC-html40/frameset.dtd">
<HTML>
<HEAD>
<meta name="generator" content="JDiff v1.1.1">
<!-- Generated by the JDiff Javadoc doclet -->
<!-- (http://www.jdiff.org) -->
<meta name="description" content="JDiff is a Javadoc doclet which generates an HTML report of all the packages, classes, constructors, methods, and fields which have been removed, added or changed in any way, including their documentation, when two APIs are compared.">
<meta name="keywords" content="diff, jdiff, javadiff, java diff, java difference, API difference, difference between two APIs, API diff, Javadoc, doclet">
<LINK REL="stylesheet" TYPE="text/css" HREF="../stylesheet-jdiff.css" TITLE="Style">
<TITLE>
com.google.inject Documentation Differences
</TITLE>
</HEAD>
<BODY>
<!-- Start of nav bar -->
<TABLE summary="Navigation bar" BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<TABLE summary="Navigation bar" BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../2.0/com/google/inject/package-summary.html" target="_top"><FONT CLASS="NavBarFont1"><B><tt>2.0</tt></B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="changes-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> &nbsp;<FONT CLASS="NavBarFont1">Package</FONT>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1"> &nbsp;<FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="docdiffs_index.html"><FONT CLASS="NavBarFont1"><B>Text Changes</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_statistics.html"><FONT CLASS="NavBarFont1"><B>Statistics</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_help.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM><b>Generated by<br><a href="http://www.jdiff.org" class="staysblack" target="_top">JDiff</a></b></EM></TD>
</TR>
<TR>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell2"><FONT SIZE="-2">
<B>PREV PACKAGE</B> &nbsp;
&nbsp;<A HREF="docdiffs_com.google.inject.binder.html"><B>NEXT PACKAGE</B></A>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<A HREF="../changes.html" TARGET="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="docdiffs_com.google.inject.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell2">&nbsp;</TD>
</TR>
</TABLE>
<HR>
<!-- End of nav bar -->
<h2>
com.google.inject Documentation Differences
</h2>
<blockquote>
This file contains all the changes in documentation in the package <code>com.google.inject</code> as colored differences.
Deletions are shown <strike>like this</strike>, and
additions are shown <span style="background: #FFFF00">like this</span>.
</blockquote>
<blockquote>
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The <i>new</i> 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.
</blockquote>
<blockquote>
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 &lt;code&gt; tag will cause all subsequent paragraphs to be displayed differently.
</blockquote>
<hr>
<A NAME="com.google.inject.AbstractModule!class"></A><a href="com.google.inject.AbstractModule.html" class="hiddenlink">Class <b>AbstractModule</b></a><br><br><blockquote>A support class for <A HREF="../2.0/com/google/inject/AbstractModule/Module.html"><TT>Module</TT></A>s which reduces repetition and results in
a more readable configuration. Simply extend this class, implement <A HREF="../2.0/com/google/inject/AbstractModule/.html#configure()"><TT>.configure()</TT></A>, and call the inherited methods which mirror those found in
<A HREF="../2.0/com/google/inject/AbstractModule/Binder.html"><TT>Binder</TT></A>. For example:
<pre>
<strike>import static com.google.inject.Names.named;
</strike>public class MyModule extends AbstractModule {
protected void configure() {
bind(<strike>Foo</strike><span style="background: #FFFF00">Service</span>.class).to(<strike>FooImpl</strike><span style="background: #FFFF00">ServiceImpl</span>.class).in(<strike>Scopes</strike><span style="background: #FFFF00">Singleton</span>.<strike>SINGLETON</strike><span style="background: #FFFF00">class</span>);
bind(<strike>BarImpl</strike><span style="background: #FFFF00">CreditCardPaymentService</span>.class);
<strike>link</strike><span style="background: #FFFF00">bind</span>(<strike>Bar</strike><span style="background: #FFFF00">PaymentService</span>.class).to(<strike>BarImpl</strike><span style="background: #FFFF00">CreditCardPaymentService</span>.class);
bindConstant(<span style="background: #FFFF00">).annotatedWith(Names.</span>named("port")).to(8080);
}
}
</pre>
@author [email protected] (Bob Lee)</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Binder!class"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a><br><br><blockquote>Collects configuration information (primarily <i>bindings</i>) which will be
used to create an <A HREF="../2.0/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A>. Guice provides this object to your
application's <A HREF="../2.0/com/google/inject/Binder/Module.html"><TT>Module</TT></A><strike>s</strike><span style="background: #FFFF00"> implementors</span> so they may each contribute
their own bindings<span style="background: #FFFF00"> and other registrations</span>.
<h3>The <span style="background: #FFFF00">Guice Binding EDSL</h3>
Guice uses an <i>embedded domain-specific language</i>, or EDSL, to help you
create </span>bindings <strike>contributed</strike><span style="background: #FFFF00">simply and readably. This approach is great for overall
usability, but it does come with a small</span> <span style="background: #FFFF00">cost: <b>it is difficult to
learn how to use the Binding EDSL </span>by <span style="background: #FFFF00">reading
method-level javadocs</b>. Instead, you should consult the series of
examples below. To save space, these examples omit the opening
</span>{@code <strike>Module</strike><span style="background: #FFFF00">binder</span>}<strike>s</strike><span style="background: #FFFF00">,</span> <strike>define</strike><span style="background: #FFFF00">just</span> <strike>how</strike><span style="background: #FFFF00">as you will if your</span> <span style="background: #FFFF00">module extends
<A HREF="../2.0/com/google/inject/Binder/AbstractModule.html"><TT>AbstractModule</TT></A>.
<pre>
bind(ServiceImpl.class);</pre>
This statement does essentially nothing; it "binds </span>the {@<strike>code
Injector</strike><span style="background: #FFFF00">code ServiceImpl</span>}<span style="background: #FFFF00">
class to itself" and does not change Guice's</span> <strike>resolves dependencies</strike><span style="background: #FFFF00">default behavior</span>. <strike>A</strike><span style="background: #FFFF00"> You may still
want to use this</span> <span style="background: #FFFF00">if you prefer your <A HREF="../2.0/com/google/inject/Binder/Module.html"></span><TT><strike>Key</strike><span style="background: #FFFF00">Module</span></TT></A> <strike>consisting</strike><span style="background: #FFFF00">class</span> <strike>of</strike><span style="background: #FFFF00">to serve as an
explicit <i>manifest</i> for the services it provides. Also, in</span> <span style="background: #FFFF00">rare cases,
Guice may be unable to validate </span>a <strike>type
and optional</strike><span style="background: #FFFF00">binding at injector</span> <strike>annotation</strike><span style="background: #FFFF00">creation time unless it
is given explicitly.
<pre>
</span> <strike>uniquely</strike> <strike>identifies</strike> <span style="background: #FFFF00"> bind(Service.class).to(ServiceImpl.class);</pre>
Specifies that a request for a {@code Service} instance with no binding
annotations should be treated as if it were </span>a <span style="background: #FFFF00">request for a
{@code ServiceImpl} instance. This <i>overrides</i> the function of any
<A HREF="../2.0/com/google/inject/Binder/ImplementedBy.html"><TT>@ImplementedBy</TT></A> or <A HREF="../2.0/com/google/inject/Binder/ProvidedBy.html"><TT>@ProvidedBy</TT></A>
annotations found on {@code Service}, since Guice will have already
"moved on" to {@code ServiceImpl} before it reaches the point when it starts
looking for these annotations.
<pre>
bind(Service.class).toProvider(ServiceProvider.class);</pre>
In this example, {@code ServiceProvider} must extend or implement
{@code Provider<Service>}. This </span>binding <strike>within</strike><span style="background: #FFFF00">specifies that Guice should resolve
</span> an <span style="background: #FFFF00">unannotated injection request for </span>{@<strike>code
</strike><span style="background: #FFFF00">code</span> <strike>Injector</strike><span style="background: #FFFF00">Service} by first resolving an
instance of {@code ServiceProvider} in the regular way, then calling
<A HREF="../2.0/com/google/inject/Binder/Provider.html#get"><TT>get()</TT></A> on the resulting Provider instance to obtain the
{@code Service</span>}<span style="background: #FFFF00"> instance</span>.
<p><strike>You</strike><span style="background: #FFFF00">The</span> <strike>may</strike><A HREF="../2.0/com/google/inject/Binder/Provider.html"><TT><span style="background: #FFFF00">Provider</TT></A></span> <strike>bind from</strike><span style="background: #FFFF00">you use</span> <strike>a</strike><span style="background: #FFFF00">here does</span> <strike>key</strike><span style="background: #FFFF00">not have</span> to<strike>:
</strike> <strike>
</strike><span style="background: #FFFF00">be</span> <strike>Another</strike><span style="background: #FFFF00">a</span> <strike>binding</strike><span style="background: #FFFF00">"factory"; that
is</span>, <span style="background: #FFFF00">a provider </span>which <span style="background: #FFFF00">always <i>creates</i> each instance it provides.
However, </span>this <strike>binding</strike><span style="background: #FFFF00">is generally a good practice to follow. You can then use
Guice</span>'s <strike>key</strike><span style="background: #FFFF00">concept</span> <strike>is</strike><span style="background: #FFFF00">of <A HREF="../2.0/com/google/inject/Binder/Scope.html"><TT>scopes</TT></A> to guide when creation should</span> <strike>now</strike><span style="background: #FFFF00">happen
--</span> "<strike>aliased</strike><span style="background: #FFFF00">letting</span> <strike>to</strike><span style="background: #FFFF00">Guice work for you</span>"<span style="background: #FFFF00">.
<pre></span>
<strike>Another</strike><span style="background: #FFFF00"> bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);</pre>
Like the previous example, but only applies to injection requests that</span> <span style="background: #FFFF00">use
the </span>binding<span style="background: #FFFF00"> annotation {@code @Red}. If your module also includes bindings
for particular <i>values</i> of the {@code @Red} annotation (see below)</span>,<span style="background: #FFFF00">
</span> <strike>which</strike><span style="background: #FFFF00">then this binding will serve</span> <strike>references</strike><span style="background: #FFFF00">as</span> a <strike>Provider</strike><span style="background: #FFFF00">"catch-all"</span> for <strike>this key
</strike><span style="background: #FFFF00">any values</span> <strike>A</strike><span style="background: #FFFF00">of</span> <strike>preconstructed</strike><span style="background: #FFFF00">{@code</span> <strike>instance
</strike><span style="background: #FFFF00">@Red}
</span> <strike>A</strike><span style="background: #FFFF00">that</span> <strike>preconstructed instance which should be used</strike><span style="background: #FFFF00">have no exact match in the</span> <strike>as</strike><span style="background: #FFFF00">bindings.
<pre>
bind(ServiceImpl.class).in(Singleton.class);
// or,</span> <span style="background: #FFFF00">alternatively
bind(ServiceImpl.class).in(Scopes.SINGLETON);</pre>
Either of these statements places </span>the <strike>Provider</strike><span style="background: #FFFF00">{@code ServiceImpl} class into
singleton scope. Guice will create only one instance of {@code ServiceImpl}</span>
<span style="background: #FFFF00">and will reuse</span> <span style="background: #FFFF00">it</span> for <span style="background: #FFFF00">all injection requests of </span>this <strike>binding
</strike><span style="background: #FFFF00">type.</span> <strike>
</strike> <strike>In</strike><span style="background: #FFFF00">Note</span> <strike>addition,</strike><span style="background: #FFFF00">that</span> <strike>a</strike><span style="background: #FFFF00">it is
still possible to bind another instance</span> <span style="background: #FFFF00">of {@code ServiceImpl} if the second
</span>binding <strike>may have</strike><span style="background: #FFFF00">is qualified</span> <span style="background: #FFFF00">by </span>an <strike>associated</strike><span style="background: #FFFF00">annotation</span> <strike>scope</strike><span style="background: #FFFF00">as in the previous example. Guice is
not overly concerned with <i>preventing</i> you from creating multiple
instances of your "singletons"</span>, <strike>such</strike><span style="background: #FFFF00">only with <i>enabling</i> your application to
share only one instance if that's all you tell Guice you need.
<p><b>Note:</b> a scope</span> <strike>as
</strike><span style="background: #FFFF00">specified</span> <span style="background: #FFFF00">in this way <i>overrides</i> any scope that
was specified with an annotation on the {@code ServiceImpl} class.
<p>Besides <A HREF="../2.0/com/google/inject/Binder/Singleton.html"><TT>Singleton</TT></A>/</span><A HREF="../2.0/com/google/inject/Binder/Scopes.html#SINGLETON"><TT>Scopes.SINGLETON</TT></A>, <span style="background: #FFFF00">there are
servlet-specific scopes available in
{@code com.google.inject.servlet.ServletScopes}, </span>and <strike>singleton bindings may specify eager</strike><span style="background: #FFFF00">your Modules can
contribute their</span> <strike>or</strike><span style="background: #FFFF00">own custom scopes for</span> <strike>lazy
</strike><span style="background: #FFFF00">use</span> <strike>initialization</strike><span style="background: #FFFF00">here as well</span>.
<strike>See</strike><pre><span style="background: #FFFF00">
bind(new TypeLiteral&lt;PaymentService&lt;CreditCard>>() {})
</span> <span style="background: #FFFF00"> .to(CreditCardPaymentService.class);</pre>
This admittedly odd construct is </span>the <strike>users'</strike><span style="background: #FFFF00">way</span> <strike>guide</strike><span style="background: #FFFF00">to bind a parameterized type. It
tells Guice how to honor an injection request for an element of type
{@code PaymentService<CreditCard>}. The class
{@code CreditCardPaymentService} must implement the
{@code PaymentService<CreditCard>} interface. Guice cannot currently bind</span> <strike>appendix</strike><span style="background: #FFFF00">or
inject a generic type</span>, <strike>"How</strike><span style="background: #FFFF00">such</span> <strike>the</strike><span style="background: #FFFF00">as</span> <strike>Injector</strike><span style="background: #FFFF00">{@code Set<E>}; all</span> <strike>resolves injection
</strike><span style="background: #FFFF00">type parameters</span> <strike>requests</strike><span style="background: #FFFF00">must be
fully specified.
<pre>
bind(Service.class).toInstance(new ServiceImpl());
// or</span>,<strike>"</strike> <strike>to</strike><span style="background: #FFFF00">alternatively
</span> <strike>better</strike> <strike>understand</strike> <strike>binding</strike> <strike>resolution</strike><span style="background: #FFFF00"> bind(Service.class)</span>.<span style="background: #FFFF00">toInstance(SomeLegacyRegistry.getService());</pre></span>
<strike>After</strike><span style="background: #FFFF00">In</span> <strike>an</strike><span style="background: #FFFF00">this example, your module itself, <i>not Guice</i>, takes responsibility
for obtaining a</span> {@code <strike>Injector</strike><span style="background: #FFFF00">ServiceImpl</span>} <strike>has</strike><span style="background: #FFFF00">instance, then asks Guice to always use
this single instance to fulfill all {@code Service} injection requests. When
the <A HREF="../2.0/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A></span> <strike>been</strike><span style="background: #FFFF00">is</span> created, <strike>its</strike><span style="background: #FFFF00">it</span> <strike>bindings may</strike><span style="background: #FFFF00">will automatically</span> <strike>be
</strike><span style="background: #FFFF00">perform field
and method injection for this instance, but any injectable constructor on
{@code ServiceImpl} is simply ignored. </span> <strike>examined</strike><span style="background: #FFFF00">Note</span> <span style="background: #FFFF00">that </span>using <strike>methods</strike><span style="background: #FFFF00">this approach results
in "eager loading" behavior that you can't control.
<pre>
bindConstant().annotatedWith(ServerHost.class).to(args[0]);</pre>
Sets up a constant binding. Constant injections must always be annotated.
When a constant binding's value is a string, it</span> <strike>like</strike><span style="background: #FFFF00">is eligile for conversion to
all primitive</span> <span style="background: #FFFF00">types, to <A HREF="../2.0/com/google/inject/Binder/Enum.html#valueOf(Class, String)"></span><TT><strike>Injector</strike><span style="background: #FFFF00">all enums</TT></A>, and to
<A HREF="../2.0/com/google/inject/Binder/Class.html#forName"><TT>class literals</TT></A></span>.<strike>getBinding</strike><span style="background: #FFFF00"> Conversions for other types can be
configured using <A HREF="../2.0/com/google/inject/Binder/.html#convertToTypes(Matcher, TypeConverter)"><TT> convertToTypes</span>(<strike>Key</strike>)</TT></A><span style="background: #FFFF00">.
<pre>
{@literal @}Color("red") Color red; // A member variable (field)
. . .
red = MyModule.class.getDeclaredField("red").getAnnotation(Color.class);
bind(Service.class).annotatedWith(red).to(RedService.class);</pre>
If your binding annotation has parameters you can apply different bindings to
different specific values of your annotation. Getting your hands on the
right instance of the annotation is a bit of a pain -- one approach</span>, <strike>but</strike><span style="background: #FFFF00">shown
above, is to</span> <strike>this
</strike><span style="background: #FFFF00">apply</span> <span style="background: #FFFF00">a prototype annotation to a field in your module class, so
that you can </span>read<strike>-only</strike><span style="background: #FFFF00"> this annotation instance and give it to Guice.
<pre>
bind(Service.class)
.annotatedWith(Names.named("blue"))
.to(BlueService.class);</pre>
Differentiating by names is a common enough use case that we provided a
standard annotation,</span> <A HREF="../2.0/com/google/inject/Binder/com/google/inject/name/Named.html"><TT><strike>Binding</strike><span style="background: #FFFF00">@Named</span></TT></A><span style="background: #FFFF00">.</span> <strike>type</strike><span style="background: #FFFF00"> Because of
Guice's library support, binding by name</span> is <strike>not used when</strike><span style="background: #FFFF00">quite easier than</span> <strike>creating</strike><span style="background: #FFFF00">in</span> the
<strike>bindings</strike><span style="background: #FFFF00">arbitrary binding annotation case we just saw. However, remember that these
names will live in a single flat namespace with all the other names used in
your application.
<p>The above list of examples is far from exhaustive. If you can think of
how the concepts of one example might coexist with the concepts from another,
you can most likely weave the two together. If the two concepts make no
sense with each other, you most likely won't be able to do it. In a few
cases Guice will let something bogus slip by, and will then inform you of
the problems at runtime, as soon as you try to create your Injector</span>.<span style="background: #FFFF00">
<p>The other methods of Binder such as <A HREF="../2.0/com/google/inject/Binder/.html#bindScope"><TT>.bindScope</TT></A>,
<A HREF="../2.0/com/google/inject/Binder/.html#bindInterceptor"><TT>.bindInterceptor</TT></A>, <A HREF="../2.0/com/google/inject/Binder/.html#install"><TT>.install</TT></A>, <A HREF="../2.0/com/google/inject/Binder/.html#requestStaticInjection"><TT>.requestStaticInjection</TT></A>,
<A HREF="../2.0/com/google/inject/Binder/.html#addError"><TT>.addError</TT></A> and <A HREF="../2.0/com/google/inject/Binder/.html#currentStage"><TT>.currentStage</TT></A> are not part of the Binding EDSL;
you can learn how to use these in the usual way, from the method
documentation.
@author [email protected] (Bob Lee)
@author [email protected] (Jesse Wilson)
@author [email protected] (Kevin Bourrillion)</span></blockquote>
<A NAME="com.google.inject.Binder.dmethod.bind(Class&lt;T&gt;)"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.bind_changed(java.lang.Class<T>)" class="hiddenlink">AnnotatedBindingBuilder&lt;T&gt; <b>bind(Class&lt;T&gt;)</b></a><br><br><blockquote><strike>Creates a binding to a</strike><span style="background: #FFFF00">See the EDSL examples at</span> <strike>type</strike><A HREF="../2.0/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote>
<A NAME="com.google.inject.Binder.dmethod.bind(Key&lt;T&gt;)"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.bind_changed(com.google.inject.Key<T>)" class="hiddenlink">LinkedBindingBuilder&lt;T&gt; <b>bind(Key&lt;T&gt;)</b></a><br><br><blockquote><strike>Creates a binding to a</strike><span style="background: #FFFF00">See the EDSL examples at</span> <strike>key</strike><A HREF="../2.0/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote>
<A NAME="com.google.inject.Binder.dmethod.bind(TypeLiteral&lt;T&gt;)"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.bind_changed(com.google.inject.TypeLiteral<T>)" class="hiddenlink">AnnotatedBindingBuilder&lt;T&gt; <b>bind(TypeLiteral&lt;T&gt;)</b></a><br><br><blockquote><strike>Creates a binding to a</strike><span style="background: #FFFF00">See the EDSL examples at</span> <strike>type</strike><A HREF="../2.0/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote>
<A NAME="com.google.inject.Binder.dmethod.bindConstant()"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.bindConstant_changed()" class="hiddenlink">AnnotatedConstantBindingBuilder <b>bindConstant()</b></a><br><br><blockquote><strike>Binds a constant value to</strike><span style="background: #FFFF00">See the EDSL examples at</span> <strike>an annotation</strike><A HREF="../2.0/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote>
<A NAME="com.google.inject.Binder.dmethod.bindInterceptor(Matcher&lt;Class&lt;?&gt;&gt;, Matcher&lt;Method&gt;, MethodInterceptor[])"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.bindInterceptor_changed(com.google.inject.matcher.Matcher<? super java.lang.Class<?>>, com.google.inject.matcher.Matcher<? super java.lang.reflect.Method>, org.aopalliance.intercept.MethodInterceptor[])" class="hiddenlink">void <b>bindInterceptor(Matcher&lt;Class&lt;?&gt;&gt;, Matcher&lt;Method&gt;, MethodInterceptor[])</b></a><br><br><blockquote>Binds <strike>a </strike>method interceptor<span style="background: #FFFF00">[s]</span> to methods matched by class and <strike>method
</strike><span style="background: #FFFF00">method</span> matchers.<span style="background: #FFFF00"> A method is
eligible for interception if:
<ul>
<li>Guice created the instance the method is on</li>
<li>Neither the enclosing type nor the method is final</li>
<li>And the method is package-private, protected, or public</li>
</ul></span>
@param classMatcher matches classes the interceptor should apply to. For
example: {@code only(Runnable.class)}.
@param methodMatcher matches methods the interceptor should apply to. For
example: {@code annotatedWith(Transactional.class)}.
@param interceptors to bind</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Binding!class"></A><a href="com.google.inject.Binding.html" class="hiddenlink">Class <b>Binding</b></a><br><br><blockquote>A mapping from a key (type and optional annotation) to <strike>a</strike><span style="background: #FFFF00">the</span> <strike>provider</strike><span style="background: #FFFF00">strategy for</span> <strike>of
</strike><span style="background: #FFFF00">getting</span> instances of <strike>that</strike><span style="background: #FFFF00">the
</span> type. <strike> </strike>This interface is part of the <strike>Injector
</strike>introspection API and is intended <strike>primary</strike><span style="background: #FFFF00">primarily</span> for use by <span style="background: #FFFF00">
tools.
<p>Bindings are created in several ways:
<ul>
<li>Explicitly in a module, via {@code bind()} and {@code bindConstant()}
statements:
<pre>
bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);
bindConstant().annotatedWith(ServerHost.class).to(args[0]);</pre></li>
<li>Implicitly by the Injector by following a type's <A HREF="../2.0/com/google/inject/Binding/ImplementedBy.html"><TT> pointer</TT></A> <A HREF="../2.0/com/google/inject/Binding/ProvidedBy.html"><TT>annotations</TT></A> or by using its <A HREF="../2.0/com/google/inject/Binding/Inject.html"><TT>annotated</TT></A> or
default constructor.</li>
<li>By converting a bound instance to a different type.</li>
<li>For <A HREF="../2.0/com/google/inject/Binding/Provider.html"><TT>providers</TT></A>, by delegating to the binding for the provided type.</li>
</ul>
<p>They exist on both modules and on injectors, and their behaviour is different for each:
<ul>
<li><strong>Module bindings</strong> are incomplete and cannot be used to provide instances.
This is because the applicable scopes and interceptors may not be known until an injector
is created. From a tool's perspective, module bindings are like the injector's source
code. They can be inspected or rewritten, but this analysis must be done statically.</li>
<li><strong>Injector bindings</strong> are complete and valid and can be used to provide
instances. From a </span>tools<span style="background: #FFFF00">' perspective, injector bindings are like reflection for an
injector. They have full runtime information, including the complete graph of injections
necessary to satisfy a binding.</li>
</ul>
@param <T> the bound type. The injected is always assignable to this type</span>.
@author [email protected] (Bob Lee)<span style="background: #FFFF00">
@author [email protected] (Jesse Wilson)</span></blockquote>
<A NAME="com.google.inject.Binding.dmethod.getProvider()"></A><a href="com.google.inject.Binding.html" class="hiddenlink">Class <b>Binding</b></a>, <a href="com.google.inject.Binding.html#com.google.inject.Binding.getProvider_changed()" class="hiddenlink">Provider&lt;T&gt; <b>getProvider()</b></a><br><br><blockquote>Returns the <span style="background: #FFFF00">scoped </span>provider guice uses to fulfill requests for <strike>this</strike><span style="background: #FFFF00">this
</span> binding.<span style="background: #FFFF00">
@throws UnsupportedOperationException when invoked on a <A HREF="../2.0/Binding.html"><TT>Binding</TT></A>
created via <A HREF="../2.0/com/google/inject/spi/Elements.html#getElements"><TT>com.google.inject.spi.Elements.getElements</TT></A>. This
method is only supported on <A HREF="../2.0/Binding.html"><TT>Binding</TT></A>s returned from an injector.</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.BindingAnnotation!class"></A><a href="com.google.inject.BindingAnnotation.html" class="hiddenlink">Class <b>BindingAnnotation</b></a><br><br><blockquote>Annotates annotations which are used for binding. Only one such annotation
may apply to a single injection point. You must also annotate binder
annotations with {@code @Retention(RUNTIME)}. For example:
<pre>
{@code @}Retention(RUNTIME)
{@code @}Target({ FIELD, PARAMETER<span style="background: #FFFF00">, METHOD</span> })
{@code @}BindingAnnotation
public {@code @}interface Transactional {}
</pre>
@author [email protected] (Bob Lee)</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.CreationException!class"></A><a href="com.google.inject.CreationException.html" class="hiddenlink">Class <b>CreationException</b></a><br><br><blockquote>Thrown when errors occur while creating a <A HREF="../2.0/com/google/inject/CreationException/Injector.html"><TT>Injector</TT></A>. Includes a <strike>list
</strike><span style="background: #FFFF00">list</span> of <strike>encountered</strike><span style="background: #FFFF00">encountered
</span> errors. <strike>Typically, a client</strike><span style="background: #FFFF00">Clients</span> should catch this exception, <strike>log
</strike><span style="background: #FFFF00">log</span> it, and stop execution.
@author [email protected] (Bob Lee)</blockquote>
<A NAME="com.google.inject.CreationException.ctor(Collection&lt;Message&gt;)"></A><a href="com.google.inject.CreationException.html" class="hiddenlink">Class <b>CreationException</b></a>, <a href="com.google.inject.CreationException.html#com.google.inject.CreationException.ctor_changed(java.util.Collection<com.google.inject.spi.Message>)" class="hiddenlink">constructor <b>CreationException(Collection&lt;Message&gt;)</b></a><br><br><blockquote><strike>Constructs</strike><span style="background: #FFFF00">Creates</span> a <strike>new</strike><span style="background: #FFFF00">CreationException</span> <strike>exception</strike><span style="background: #FFFF00">containing</span> <strike>for</strike><span style="background: #FFFF00">{@code</span> <strike>the given errors</strike><span style="background: #FFFF00">messages}</span>.</blockquote>
<A NAME="com.google.inject.CreationException.dmethod.getErrorMessages()"></A><a href="com.google.inject.CreationException.html" class="hiddenlink">Class <b>CreationException</b></a>, <a href="com.google.inject.CreationException.html#com.google.inject.CreationException.getErrorMessages_changed()" class="hiddenlink">Collection&lt;Message&gt; <b>getErrorMessages()</b></a><br><br><blockquote><strike>Gets the error messages which resulted in</strike><span style="background: #FFFF00">Returns messages for the errors that caused</span> this exception.</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Guice!class"></A><a href="com.google.inject.Guice.html" class="hiddenlink">Class <b>Guice</b></a><br><br><blockquote>The entry point to the Guice framework. Creates <A HREF="../2.0/com/google/inject/Guice/Injector.html"><TT>Injector</TT></A>s from
<A HREF="../2.0/com/google/inject/Guice/Module.html"><TT>Module</TT></A>s.<span style="background: #FFFF00">
<p>Guice supports a model of development that draws clear boundaries between
APIs, Implementations of these APIs, Modules which configure these
implementations, and finally Applications which consist of a collection of
Modules. It is the Application, which typically defines your {@code main()}
method, that bootstraps the Guice Injector using the {@code Guice} class, as
in this example:
<pre>
public class FooApplication {
public static void main(String[] args) {
Injector injector = Guice.createInjector(
new ModuleA(),
new ModuleB(),
. . .
new FooApplicationFlagsModule(args)
);
// Now just bootstrap the application and you're done
FooStarter starter = injector.getInstance(FooStarter.class);
starter.runApplication();
}
}
</pre></span></blockquote>
<A NAME="com.google.inject.Guice.dmethod.createInjector(Module[])"></A><a href="com.google.inject.Guice.html" class="hiddenlink">Class <b>Guice</b></a>, <a href="com.google.inject.Guice.html#com.google.inject.Guice.createInjector_changed(com.google.inject.Module[])" class="hiddenlink">Injector <b>createInjector(Module[])</b></a><br><br><blockquote>Creates an injector for the given set of modules.
@throws CreationException <strike>from which you can retrieve</strike><span style="background: #FFFF00">if one or more errors</span> <strike>the</strike><span style="background: #FFFF00">occur during Injector
</span> <strike>individual</strike> <strike>error
</strike> <strike>messages</strike><span style="background: #FFFF00">construction</span></blockquote>
<A NAME="com.google.inject.Guice.dmethod.createInjector(Stage, Module[])"></A><a href="com.google.inject.Guice.html" class="hiddenlink">Class <b>Guice</b></a>, <a href="com.google.inject.Guice.html#com.google.inject.Guice.createInjector_changed(com.google.inject.Stage, com.google.inject.Module[])" class="hiddenlink">Injector <b>createInjector(Stage, Module[])</b></a><br><br><blockquote>Creates an injector for the given set of modules, in a given development
stage.
@throws CreationException <strike>from which you can retrieve the individual error
</strike><span style="background: #FFFF00">if one or more errors occur during Injector
</span> <strike>messages.</strike><span style="background: #FFFF00"> creation</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Injector!class"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a><br><br><blockquote><strike>Fulfills</strike><span style="background: #FFFF00">Builds</span> <strike>requests for </strike>the <strike>object</strike><span style="background: #FFFF00">graphs</span> <strike>instances</strike><span style="background: #FFFF00">of objects</span> that make up your application<strike>,
</strike><span style="background: #FFFF00">.</span> <strike>always ensuring that these instances are properly injected before they are
</strike><span style="background: #FFFF00">The injector tracks the dependencies
for each type and uses bindings</span> <strike>returned.</strike><span style="background: #FFFF00">to</span> <strike>The</strike><span style="background: #FFFF00">inject</span> <strike>{@code</strike><span style="background: #FFFF00">them.</span> <strike>Injector}</strike><span style="background: #FFFF00">This</span> is the <strike>heart</strike><span style="background: #FFFF00">core</span> of <strike>the </strike>Guice<strike> framework</strike>,<strike>
</strike> although you <strike>don't typically</strike><span style="background: #FFFF00">rarely
</span> interact with it directly<strike> very often</strike>. <strike>This
</strike><span style="background: #FFFF00">This</span> "behind-the-scenes" operation is what distinguishes <strike>the </strike>dependency
injection <strike>pattern </strike>from its cousin, <span style="background: #FFFF00">the </span>service locator<strike>.
The {@code Injector} API has a few additional features: it allows
pre-constructed instances to have their fields and</strike> <strike>methods injected and
offers programmatic introspection to support tool development</strike><span style="background: #FFFF00">pattern</span>.
<p>Contains several default bindings:
<ul>
<li>This <A HREF="../2.0/com/google/inject/Injector/Injector.html"><TT>Injector</TT></A> instance itself
<li>A {@code Provider<T>} for each binding of type {@code T}
<li>The <A HREF="../2.0/com/google/inject/Injector/java/util/logging/Logger.html"><TT>java.util.logging.Logger</TT></A> for the class being injected
<li>The <A HREF="../2.0/com/google/inject/Injector/Stage.html"><TT>Stage</TT></A> in which the Injector was created
</ul>
Injectors are created using the facade class <A HREF="../2.0/com/google/inject/Injector/Guice.html"><TT>Guice</TT></A>.
<p><span style="background: #FFFF00">An injector can also <A HREF="../2.0/com/google/inject/Injector/.html#injectMembers(Object)"><TT>inject the dependencies</TT></A> of
already-constructed instances. This can be used to interoperate with objects created by other
frameworks or services.
<p>Injectors can be <A HREF="../2.0/com/google/inject/Injector/.html#createChildInjector(Iterable)"><TT>hierarchical</TT></A>. Child injectors inherit
the configuration of their parent injectors, but the converse does not hold.
<p>The injector's <A HREF="../2.0/com/google/inject/Injector/.html#getBindings()"><TT>internal bindings</TT></A> are available for introspection. This
enables tools and extensions to operate on an injector reflectively.
</span>@author [email protected] (Bob Lee)<span style="background: #FFFF00">
@author [email protected] (Jesse Wilson)</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.findBindingsByType(TypeLiteral&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.findBindingsByType_changed(com.google.inject.TypeLiteral<T>)" class="hiddenlink">List&lt;Binding&lt;T&gt;&gt; <b>findBindingsByType(TypeLiteral&lt;T&gt;)</b></a><br><br><blockquote><strike>Finds</strike><span style="background: #FFFF00">Returns</span> all <span style="background: #FFFF00">explicit </span>bindings <strike>to</strike><span style="background: #FFFF00">for {@code type}.
<p>This method is part of</span> the <strike>given</strike><span style="background: #FFFF00">Guice</span> <strike>type</strike><span style="background: #FFFF00">SPI and is intended for use by tools and extensions</span>.</blockquote>
<A NAME="com.google.inject.Injector.dmethod.getBinding(Key&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getBinding_changed(com.google.inject.Key<T>)" class="hiddenlink">Binding&lt;T&gt; <b>getBinding(Key&lt;T&gt;)</b></a><br><br><blockquote><strike>Gets a</strike><span style="background: #FFFF00">Returns the</span> binding for the given <span style="background: #FFFF00">injection </span>key.<span style="background: #FFFF00"> This will be an explicit bindings if the key
was bound explicitly by a module, or an implicit binding otherwise. The implicit binding will
be created if necessary.
<p>This method is part of the Guice SPI and is intended for use by tools and extensions.
@throws ConfigurationException if this injector cannot find or create the binding.</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.getBindings()"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getBindings_changed()" class="hiddenlink">Map&lt;Key&lt;?&gt;, Binding&lt;?&gt;&gt; <b>getBindings()</b></a><br><br><blockquote><strike>Gets</strike><span style="background: #FFFF00">Returns</span> all explicit bindings.<span style="background: #FFFF00">
<p>The returned map does not include bindings inherited from a <A HREF="../2.0/.html#getParent()"><TT>parent
injector</TT></A>, should one exist. The returned map is guaranteed to iterate (for example, with
its <A HREF="../2.0/java/util/Map.html#entrySet()"><TT>java.util.Map.entrySet()</TT></A> iterator) in the order of insertion. In other words,
the order in which bindings appear in user Modules.
<p>This method is part of the Guice SPI and is intended for use by tools and extensions.</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.getInstance(Class&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getInstance_changed(java.lang.Class<T>)" class="hiddenlink">T <b>getInstance(Class&lt;T&gt;)</b></a><br><br><blockquote><strike>Gets an instance bound to</strike><span style="background: #FFFF00">Returns the appropriate instance for</span> the given <span style="background: #FFFF00">injection </span>type; equivalent <strike>to
</strike><span style="background: #FFFF00">to</span> {@<strike>code</strike><span style="background: #FFFF00">code
</span> getProvider(type).get()}.<span style="background: #FFFF00"> When feasible, avoid using this method, in favor of having Guice
inject your dependencies ahead of time.
@throws ConfigurationException if this injector cannot find or create the provider.
@throws ProvisionException if there was a runtime failure while providing an instance.</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.getInstance(Key&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getInstance_changed(com.google.inject.Key<T>)" class="hiddenlink">T <b>getInstance(Key&lt;T&gt;)</b></a><br><br><blockquote><strike>Gets an instance bound to</strike><span style="background: #FFFF00">Returns the appropriate instance for</span> the given <span style="background: #FFFF00">injection </span>key; equivalent <strike>to
</strike><span style="background: #FFFF00">to</span> {@<strike>code</strike><span style="background: #FFFF00">code
</span> getProvider(key).get()}.<span style="background: #FFFF00"> When feasible, avoid using this method, in favor of having Guice
inject your dependencies ahead of time.
@throws ConfigurationException if this injector cannot find or create the provider.
@throws ProvisionException if there was a runtime failure while providing an instance.</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.getProvider(Class&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getProvider_changed(java.lang.Class<T>)" class="hiddenlink">Provider&lt;T&gt; <b>getProvider(Class&lt;T&gt;)</b></a><br><br><blockquote><strike>Gets</strike><span style="background: #FFFF00">Returns</span> the provider <strike>bound</strike><span style="background: #FFFF00">used</span> to <span style="background: #FFFF00">obtain instances for </span>the given type.<span style="background: #FFFF00"> When feasible, avoid
using this method, in favor of having Guice inject your dependencies ahead of time.
@throws ConfigurationException if this injector cannot find or create the provider.
@see Binder#getProvider(Class) for an alternative that offers up front error detection</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.getProvider(Key&lt;T&gt;)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getProvider_changed(com.google.inject.Key<T>)" class="hiddenlink">Provider&lt;T&gt; <b>getProvider(Key&lt;T&gt;)</b></a><br><br><blockquote><strike>Gets</strike><span style="background: #FFFF00">Returns</span> the provider <strike>bound</strike><span style="background: #FFFF00">used</span> to <span style="background: #FFFF00">obtain instances for </span>the given <span style="background: #FFFF00">injection </span>key.<span style="background: #FFFF00"> When feasible, avoid
using this method, in favor of having Guice inject your dependencies ahead of time.
@throws ConfigurationException if this injector cannot find or create the provider.
@see Binder#getProvider(Key) for an alternative that offers up front error detection</span></blockquote>
<A NAME="com.google.inject.Injector.dmethod.injectMembers(Object)"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.injectMembers_changed(java.lang.Object)" class="hiddenlink">void <b>injectMembers(Object)</b></a><br><br><blockquote>Injects dependencies into the fields and methods of <span style="background: #FFFF00">{@code instance}. Ignores the presence or
absence of </span>an <strike>existing object</strike><span style="background: #FFFF00">injectable constructor</span>.<strike>
</strike><span style="background: #FFFF00">
</span> <strike>Does</strike><p><span style="background: #FFFF00">Whenever</span> <strike>not inject</strike><span style="background: #FFFF00">Guice creates</span> <strike>the</strike><span style="background: #FFFF00">an instance, it</span> <span style="background: #FFFF00">performs this injection automatically (after first
performing </span>constructor<span style="background: #FFFF00"> injection), so if you're able to let Guice create all your objects for
you, you'll never need to use this method</span>.<span style="background: #FFFF00">
@param instance to inject members on
@see Binder#getMembersInjector(Class) for a preferred alternative that supports checks before
run time</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Key!class"></A><a href="com.google.inject.Key.html" class="hiddenlink">Class <b>Key</b></a><br><br><blockquote>Binding key consisting of an injection type and an optional annotation.
Matches the type and annotation at a point of injection.
<p>For example, {@code Key.get(Service.class, Transactional.class)} will
match:
<pre>
{@literal @}Inject
public void setService({@literal @}Transactional Service service) {
...
}
</pre>
<p>{@code Key} supports generic types via subclassing just like <A HREF="../2.0/com/google/inject/Key/TypeLiteral.html"><TT>TypeLiteral</TT></A>.
<p><span style="background: #FFFF00">Keys do not differentiate between primitive types (int, char, etc.) and
their correpsonding wrapper types (Integer, Character, etc.). Primitive
types will be replaced with their wrapper types when keys are created.
</span>@author [email protected] (Bob Lee)</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Module!class"></A><a href="com.google.inject.Module.html" class="hiddenlink">Class <b>Module</b></a><br><br><blockquote>A module contributes configuration information, typically interface
bindings, which will be used to create an <A HREF="../2.0/com/google/inject/Module/Injector.html"><TT>Injector</TT></A>. A <strike>guice</strike><span style="background: #FFFF00">Guice</span>-based
application is ultimately composed of little more than a set of
{@code Module}s and some bootstrapping code.
<p>Your Module classes can use a more streamlined syntax by extending
<A HREF="../2.0/com/google/inject/Module/AbstractModule.html"><TT>AbstractModule</TT></A> rather than implementing this interface directly.<span style="background: #FFFF00">
<p>In addition to the bindings configured via <A HREF="../2.0/com/google/inject/Module/.html#configure"><TT>.configure</TT></A>, bindings
will be created for all methods annotated with {@literal @}<A HREF="../2.0/com/google/inject/Module/Provides.html"><TT>Provides</TT></A>.
Use scope and binding annotations on these methods to configure the
bindings.</span></blockquote>
<A NAME="com.google.inject.Module.dmethod.configure(Binder)"></A><a href="com.google.inject.Module.html" class="hiddenlink">Class <b>Module</b></a>, <a href="com.google.inject.Module.html#com.google.inject.Module.configure_changed(com.google.inject.Binder)" class="hiddenlink">void <b>configure(Binder)</b></a><br><br><blockquote>Contributes bindings and other configurations <strike>to</strike><span style="background: #FFFF00">for this</span> <strike>a</strike><span style="background: #FFFF00">module to</span> {@code <strike>Binder</strike><span style="background: #FFFF00">binder</span>}.<span style="background: #FFFF00">
<p><strong>Do not invoke this method directly</strong> to install submodules. Instead use
<A HREF="../2.0/Binder.html#install(Module)"><TT>Binder.install(Module)</TT></A>, which ensures that <A HREF="../2.0/Provides.html"><TT>provider methods</TT></A> are
discovered.</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Provider!class"></A><a href="com.google.inject.Provider.html" class="hiddenlink">Class <b>Provider</b></a><br><br><blockquote><strike>Simply, any</strike><span style="background: #FFFF00">An</span> object capable of providing instances of type {@code T}.<strike>
</strike> Providers are used in numerous <strike>ways</strike><span style="background: #FFFF00">ways
</span> by <strike>the </strike>Guice<strike> framework</strike>:
<ul>
<li>When the default means for obtaining instances (an injectable <strike>or
</strike><span style="background: #FFFF00">or</span> parameterless constructor)<span style="background: #FFFF00">
</span> is insufficient for a particular binding, <strike>the
</strike><span style="background: #FFFF00">the</span> module can specify a custom {@code Provider}<span style="background: #FFFF00">
</span> instead, to control exactly <strike>how
</strike><span style="background: #FFFF00">how</span> Guice creates or obtains instances for the binding.
<li>An implementation class may always choose to have a {@code Provider<T>}<strike>
</strike> instance injected,<span style="background: #FFFF00">
</span> rather than having a {@code T} injected directly. <strike>This
</strike><span style="background: #FFFF00">This</span> may give you access to <strike>multiple</strike><span style="background: #FFFF00">multiple
</span> instances, instances you wish to <strike>safely
</strike><span style="background: #FFFF00">safely</span> mutate and discard, instances which are out of <strike>scope</strike><span style="background: #FFFF00">scope
</span> (e.g. using <strike>a
</strike><span style="background: #FFFF00">a</span> {@code @RequestScoped} object from within a {@code @SessionScoped} object),<strike>
</strike> <strike>or</strike><span style="background: #FFFF00">or
</span> instances <strike>you don't want to initialize</strike><span style="background: #FFFF00">that</span> <strike>until they</strike><span style="background: #FFFF00">will be</span> <strike>are absolutely</strike><span style="background: #FFFF00">initialized</span> <strike>needed</strike><span style="background: #FFFF00">lazily</span>.
<li>A custom <A HREF="../2.0/com/google/inject/Provider/Scope.html"><TT>Scope</TT></A> is implemented as a decorator <strike>of
</strike><span style="background: #FFFF00">of</span> {@code Provider<T>}, which <strike>decides</strike><span style="background: #FFFF00">decides
</span> when to delegate to the backing <strike>provider
</strike><span style="background: #FFFF00">provider</span> and when to provide the instance some other way.
<li>The <A HREF="../2.0/com/google/inject/Provider/Injector.html"><TT>Injector</TT></A> offers access to the {@code Provider<T>} it <strike>uses
</strike><span style="background: #FFFF00">uses</span> to fulfill <strike>requests</strike><span style="background: #FFFF00">requests
</span> for a given key, via the <A HREF="../2.0/com/google/inject/Provider/Injector.html#getProvider"><TT>Injector.getProvider</TT></A><strike>
</strike> methods.
</ul>
@param <T> the type of object this <strike>provider </strike>provides
@author [email protected] (Bob Lee)</blockquote>
<A NAME="com.google.inject.Provider.dmethod.get()"></A><a href="com.google.inject.Provider.html" class="hiddenlink">Class <b>Provider</b></a>, <a href="com.google.inject.Provider.html#com.google.inject.Provider.get_changed()" class="hiddenlink">T <b>get()</b></a><br><br><blockquote>Provides an instance of {@code T}. Must never return {@code null}.<span style="background: #FFFF00">
@throws OutOfScopeException when an attempt is made to access a scoped object while the scope
in question is not currently active
@throws ProvisionException if an instance cannot be provided. Such exceptions include messages
and throwables to describe why provision failed.</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Scope!class"></A><a href="com.google.inject.Scope.html" class="hiddenlink">Class <b>Scope</b></a><br><br><blockquote>A scope is a level of visibility that instances provided by Guice may have.
By default, an instance created by the <A HREF="../2.0/com/google/inject/Scope/Injector.html"><TT>Injector</TT></A> has <i><strike>no
</strike><span style="background: #FFFF00">no</span> scope</i>,<span style="background: #FFFF00">
</span> meaning it has no state from the framework's perspective -- the
{@code Injector} creates it, injects it once into the class that required it,
and then immediately forgets it. Associating a scope with a <strike>particular binding
</strike><span style="background: #FFFF00">particular
binding</span> allows the created instance to be "remembered" and possibly <strike>used</strike><span style="background: #FFFF00">used
</span> again <strike>for
</strike><span style="background: #FFFF00">for</span> other injections.
<strike>@see</strike><p><span style="background: #FFFF00">An example of a scope is</span> <A HREF="../2.0/com/google/inject/Scope/Scopes.html#SINGLETON"><TT>Scopes<strike>#SINGLETON
</strike><span style="background: #FFFF00">.SINGLETON</TT></A>.
</span> @author [email protected] (Bob Lee)</blockquote>
<A NAME="com.google.inject.Scope.dmethod.scope(Key&lt;T&gt;, Provider&lt;T&gt;)"></A><a href="com.google.inject.Scope.html" class="hiddenlink">Class <b>Scope</b></a>, <a href="com.google.inject.Scope.html#com.google.inject.Scope.scope_changed(com.google.inject.Key<T>, com.google.inject.Provider<T>)" class="hiddenlink">Provider&lt;T&gt; <b>scope(Key&lt;T&gt;, Provider&lt;T&gt;)</b></a><br><br><blockquote>Scopes a provider. The returned <strike>locator</strike><span style="background: #FFFF00">provider</span> returns objects from this scope.<span style="background: #FFFF00">
</span> <strike>If
</strike><span style="background: #FFFF00">If</span> an object does not exist in this scope, the provider can use the given
unscoped provider to retrieve one.
<p>Scope implementations are strongly encouraged to override
<A HREF="../2.0/Object.html#toString"><TT>Object.toString</TT></A> in the returned provider and include the backing
provider's {@code toString()} output.
@param key binding key
@param unscoped locates an instance when one doesn't already exist in this
scope.
@return a new provider which only delegates to the given unscoped provider
when an instance of the requested object doesn't already exist in this
scope</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Scopes!class"></A><a href="com.google.inject.Scopes.html" class="hiddenlink">Class <b>Scopes</b></a><br><br><blockquote>Built<strike> </strike><span style="background: #FFFF00">-</span>in scope implementations.
@author [email protected] (Bob Lee)</blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.TypeLiteral!class"></A><a href="com.google.inject.TypeLiteral.html" class="hiddenlink">Class <b>TypeLiteral</b></a><br><br><blockquote>Represents a generic type {@code T}. Java doesn't yet provide a way to
represent generic types, so this class does. Forces clients to create a
subclass of this class which enables retrieval the type information even at
runtime.
<p>For example, to create a type literal for {@code List<String>}, you can
create an empty anonymous inner class:
<p>
{@code TypeLiteral<List<String>> list = new TypeLiteral<List<String>>() {};}
<p><strike>Assumes</strike><span style="background: #FFFF00">This</span> <strike>that</strike><span style="background: #FFFF00">syntax cannot be used to</span> <span style="background: #FFFF00">create </span>type <span style="background: #FFFF00">literals that have wildcard
parameters, such as </span>{@code <strike>T</strike><span style="background: #FFFF00">Class<></span>} <strike>implements</strike><span style="background: #FFFF00">or</span> <strike>Object</strike><span style="background: #FFFF00">{@code List< extends CharSequence>}</span>.<strike>equals</strike><span style="background: #FFFF00">
Such type literals must be constructed programatically, either by <A HREF="../2.0/com/google/inject/TypeLiteral/Method.html#getGenericReturnType"><TT>extracting types from members</span></TT></A> <strike>and
</strike><span style="background: #FFFF00">or by using</span> <span style="background: #FFFF00">the
<A HREF="../2.0/com/google/inject/TypeLiteral/Types.html"></span><TT><strike>Object</strike><span style="background: #FFFF00">Types</TT></A> factory class.
<p>Along with modeling generic types, this class can resolve type parameters</span>.<strike>hashCode</strike><span style="background: #FFFF00">
For example, to figure out what type {@code keySet</span>()<span style="background: #FFFF00">}</span> <strike>as</strike><span style="background: #FFFF00">returns on a {@code
Map<Integer, String>}, use this code:<pre> {@code
</span> <strike>value</strike> <span style="background: #FFFF00"> TypeLiteral<Map<Integer, String>> mapType
= new TypeLiteral<Map<Integer, String>></span>(<strike>as</strike><span style="background: #FFFF00">) {};
</span> <strike>opposed</strike> <strike>to</strike><span style="background: #FFFF00"> TypeLiteral<> keySetType
</span> <strike>identity</strike><span style="background: #FFFF00">= mapType.getReturnType(Map.class.getMethod("keySet")</span>)<span style="background: #FFFF00">;
</span> <strike>comparison</strike><span style="background: #FFFF00"> System.out</span>.<span style="background: #FFFF00">println(keySetType); // prints "Set<Integer>"}</pre></span>
@author [email protected] (Bob Lee)<span style="background: #FFFF00">
@author [email protected] (Jesse Wilson)</span></blockquote>
<hr align="left" width="100%">
</BODY>
</HTML>