| <!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="../v2/com/google/inject/package-summary.html" target="_top"><FONT CLASS="NavBarFont1"><B><tt>v2</tt></B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="changes-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Package</FONT> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="docdiffs_index.html"><FONT CLASS="NavBarFont1"><B>Text Changes</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_statistics.html"><FONT CLASS="NavBarFont1"><B>Statistics</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_help.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </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> |
| <A HREF="docdiffs_com.google.inject.binder.html"><B>NEXT PACKAGE</B></A> |
| |
| <A HREF="../changes.html" TARGET="_top"><B>FRAMES</B></A> |
| <A HREF="docdiffs_com.google.inject.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell2"> </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 <code> 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="../v2/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="../v2/com/google/inject/AbstractModule/.html#configure()"><TT>.configure()</TT></A>, and call the inherited methods which mirror those found in |
| <A HREF="../v2/com/google/inject/AbstractModule/Binder.html"><TT>Binder</TT></A>. For example: |
| |
| <pre> |
| import static com.google.inject.Names.named; |
| |
| public class MyModule extends AbstractModule { |
| protected void configure() { |
| bind(Foo.class).to(FooImpl.class).in(Scopes.SINGLETON); |
| bind(BarImpl.class); |
| <strike>link</strike><span style="background: #FFFF00">bind</span>(Bar.class).to(BarImpl.class); |
| bindConstant(named("port")).to(8080); |
| } |
| } |
| </pre> |
| |
| @author crazybob@google.com (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="../v2/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A>. Guice provides this object to your |
| application's <A HREF="../v2/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 cost: <b>it is difficult to |
| learn how to use the Binding EDSL in the</span> <span style="background: #FFFF00">usual way -- </span>by <span style="background: #FFFF00">reading |
| method-level javadocs</b>. Instead, you should consult this 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 define</strike><span style="background: #FFFF00">, just</span> <strike>how</strike><span style="background: #FFFF00">as you will if your module extends |
| <A HREF="../v2/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</span> <strike>resolves</strike><span style="background: #FFFF00">itself" and does not change</span> <strike>dependencies</strike><span style="background: #FFFF00">Guice's default behavior</span>. <strike>A</strike><span style="background: #FFFF00"> You may still |
| want to use</span> <span style="background: #FFFF00">this if you prefer your <A HREF="../v2/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 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</span> <strike>uniquely identifies</strike><span style="background: #FFFF00">unless it |
| </span> <span style="background: #FFFF00">is given explicitly. |
| |
| <pre> |
| 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="../v2/com/google/inject/Binder/ImplementedBy.html"><TT>@ImplementedBy</TT></A> or <A HREF="../v2/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="../v2/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="../v2/com/google/inject/Binder/Provider.html"><TT><span style="background: #FFFF00">Provider</TT></A></span> <strike>bind from a key</strike><span style="background: #FFFF00">you use here does</span> <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="../v2/com/google/inject/Binder/Scope.html"><TT>scopes</TT></A> to guide when creation</span> <strike>now</strike><span style="background: #FFFF00">should 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 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 {@code</span> <strike>preconstructed</strike><span style="background: #FFFF00">@Red} |
| </span> <strike>instance |
| </strike><span style="background: #FFFF00">that</span> <strike>A</strike><span style="background: #FFFF00">have</span> <strike>preconstructed instance which should be</strike><span style="background: #FFFF00">no exact match in the</span> <strike>used</strike><span style="background: #FFFF00">bindings. |
| </span> <strike>as</strike><span style="background: #FFFF00"> |
| <pre> |
| bind(ServiceImpl.class).in(Singleton.class); |
| // or, alternatively |
| bind(ServiceImpl.class).in(Scopes.SINGLETON);</pre> |
| |
| </span> <span style="background: #FFFF00">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 of</span> <span style="background: #FFFF00">{@code ServiceImpl} if the second |
| </span>binding <strike>may</strike><span style="background: #FFFF00">is</span> <strike>have</strike><span style="background: #FFFF00">qualified 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</span> <strike>as |
| </strike><span style="background: #FFFF00">Guice you need. |
| |
| <p><b>Note:</b> a scope specified in this way <i>overrides</i> any scope that |
| was specified with an</span> <span style="background: #FFFF00">annotation on the {@code ServiceImpl} class. |
| |
| <p>Besides <A HREF="../v2/com/google/inject/Binder/Singleton.html"><TT>Singleton</TT></A>/</span><A HREF="../v2/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<PaymentService<CreditCard>>() {}) |
| .to(CreditCardPaymentService.class);</pre> |
| |
| This</span> <span style="background: #FFFF00">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 |
| </span> <strike>appendix</strike><span style="background: #FFFF00">{@code PaymentService<CreditCard>} interface. Guice cannot currently bind or |
| inject a generic type</span>, <strike>"How</strike><span style="background: #FFFF00">such as {@code Set<E>}; all type parameters must be |
| fully specified. |
| |
| <pre> |
| bind(Service.class).toInstance(new ServiceImpl()); |
| // or, alternatively |
| bind(Service.class).toInstance(SomeLegacyRegistry.getService());</pre> |
| |
| In this example, your module itself, <i>not Guice</i>, takes responsibility |
| for obtaining a {@code ServiceImpl} instance, then asks Guice to always use |
| this single instance to fulfill all {@code Service} injection requests.</span> <span style="background: #FFFF00"> When |
| </span>the <A HREF="../v2/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A> <strike>resolves injection |
| </strike><span style="background: #FFFF00">is first</span> <strike>requests</strike><span style="background: #FFFF00">created, it will automatically perform field |
| and method injection for this instance</span>,<span style="background: #FFFF00"> but any injectable constructor on |
| {@code ServiceImpl} is simply ignored. Note that using this approach results |
| in "eager loading</span>" <span style="background: #FFFF00">behavior that you can't control. |
| |
| <pre> |
| bindConstant().annotatedWith(ServerHost.class).</span>to<span style="background: #FFFF00">(args[0]);</pre> |
| |
| Sets</span> <strike>better</strike><span style="background: #FFFF00">up a</span> <strike>understand</strike><span style="background: #FFFF00">constant</span> binding<span style="background: #FFFF00">. Constant</span> <strike>resolution</strike><span style="background: #FFFF00">bindings are typeless in Guice; you |
| can provide the values in a variety of types and the values can be injected |
| in a variety of types; Guice performs the standard type conversions for you |
| behind the scenes. Because of this "typelessness", constant injections must |
| always be annotated</span>. |
| |
| <strike>After</strike><pre><span style="background: #FFFF00"> |
| </span> <strike>an</strike><span style="background: #FFFF00"> </span> {@<strike>code</strike><span style="background: #FFFF00">literal</span> <strike>Injector</strike><span style="background: #FFFF00">@</span>}<span style="background: #FFFF00">Color("red") Color red; // A member variable (field) |
| . . . |
| red = MyModule.class.getField("red").getAnnotation(Color.class); |
| bind(Service.class).annotatedWith(red).to(RedService.class);</pre> |
| |
| If</span> <span style="background: #FFFF00">your binding annotation </span>has <strike>been</strike><span style="background: #FFFF00">parameters</span> <strike>created,</strike><span style="background: #FFFF00">you</span> <strike>its</strike><span style="background: #FFFF00">can</span> <span style="background: #FFFF00">apply different </span>bindings <strike>may be |
| examined using methods like</strike><span style="background: #FFFF00">to |
| different specific values of your</span> <strike>Injector</strike><span style="background: #FFFF00">annotation. Getting your hands on the |
| right instance of the annotation is a bit of a pain -- one approach, shown |
| above, is to apply a prototype annotation to a field in your module class, so |
| that you can read this annotation instance and give it to Guice. |
| |
| <pre> |
| bind(Service.class) |
| .annotatedWith(Names.named("blue")) |
| </span>.<strike>getBinding</strike><span style="background: #FFFF00">to</span>(<strike>Key</strike><span style="background: #FFFF00">BlueService.class</span>)<span style="background: #FFFF00">;</pre> |
| |
| Differentiating by names is a common enough use case that we provided a |
| standard annotation, <A HREF="../v2/com/google/inject/Binder/com/google/inject/name/Named.html"><TT>@Named</span></TT></A><span style="background: #FFFF00">. Because of |
| Guice's library support</span>, <strike>but this |
| </strike><span style="background: #FFFF00">binding by</span> <strike>read-only</strike><span style="background: #FFFF00">name is quite easier than in the |
| arbitrary binding annotation case we just saw. However, remember that these |
| names will live in a single flat namespace</span> <span style="background: #FFFF00">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. |
| |
| <p>The other methods of Binder such as <A HREF="../v2/com/google/inject/Binder/.html#bindScope"></span><TT><strike>Binding</strike><span style="background: #FFFF00">.bindScope</span></TT></A><span style="background: #FFFF00">, |
| </span> <strike>type</strike><A HREF="../v2/com/google/inject/Binder/.html#bindInterceptor"><TT><span style="background: #FFFF00">.bindInterceptor</TT></A>,</span> <strike>is</strike><A HREF="../v2/com/google/inject/Binder/.html#install"><TT><span style="background: #FFFF00">.install</TT></A>, <A HREF="../v2/com/google/inject/Binder/.html#requestStaticInjection"><TT>.requestStaticInjection</TT></A>, |
| <A HREF="../v2/com/google/inject/Binder/.html#addError"><TT>.addError</TT></A> and <A HREF="../v2/com/google/inject/Binder/.html#currentStage"><TT>.currentStage</TT></A> are</span> not <strike>used when</strike><span style="background: #FFFF00">part of</span> <strike>creating</strike><span style="background: #FFFF00">the</span> <strike>the |
| </strike><span style="background: #FFFF00">Binding</span> <strike>bindings</strike><span style="background: #FFFF00">EDSL; |
| you can learn how to use these in the usual way, from the method |
| documentation. |
| |
| @author crazybob@google</span>.<span style="background: #FFFF00">com (Bob Lee)</span></blockquote> |
| <A NAME="com.google.inject.Binder.dmethod.bind(Class<T>)"></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<T> <b>bind(Class<T>)</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="../v2/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote> |
| <A NAME="com.google.inject.Binder.dmethod.bind(Key<T>)"></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<T> <b>bind(Key<T>)</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="../v2/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote> |
| <A NAME="com.google.inject.Binder.dmethod.bind(TypeLiteral<T>)"></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<T> <b>bind(TypeLiteral<T>)</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="../v2/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="../v2/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</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="../v2/com/google/inject/Binding/ImplementedBy.html"><TT> pointer</TT></A> <A HREF="../v2/com/google/inject/Binding/ProvidedBy.html"><TT>annotations</TT></A> or by using its <A HREF="../v2/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="../v2/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 crazybob@google.com (Bob Lee)<span style="background: #FFFF00"> |
| @author jessewilson@google.com (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<T> <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="../v2/Binding.html"><TT>Binding</TT></A> |
| created via <A HREF="../v2/com/google/inject/spi/Elements.html#getElements"><TT>com.google.inject.spi.Elements.getElements</TT></A>. This |
| method is only supported on <A HREF="../v2/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 crazybob@google.com (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="../v2/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 crazybob@google.com (Bob Lee)</blockquote> |
| <A NAME="com.google.inject.CreationException.ctor(Iterable<Message>)"></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.lang.Iterable<com.google.inject.spi.Message>)" class="hiddenlink">constructor <b>CreationException(Iterable<Message>)</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<Message> <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="../v2/com/google/inject/Guice/Injector.html"><TT>Injector</TT></A>s from |
| <A HREF="../v2/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 |
| MyStartClass starter = injector.getInstance(MyStartClass.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"> construction</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</strike> <strike>{@code Injector} API has a few additional features: it allows |
| pre-constructed instances to have their fields and 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="../v2/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="../v2/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="../v2/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="../v2/com/google/inject/Injector/Guice.html"><TT>Guice</TT></A>. |
| |
| <p><span style="background: #FFFF00">An injector can also <A HREF="../v2/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="../v2/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="../v2/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 crazybob@google.com (Bob Lee)</blockquote> |
| <A NAME="com.google.inject.Injector.dmethod.findBindingsByType(TypeLiteral<T>)"></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<Binding<T>> <b>findBindingsByType(TypeLiteral<T>)</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<T>)"></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<T> <b>getBinding(Key<T>)</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<Key<?>, Binding<?>> <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="../v2/.html#getParent()"><TT>parent |
| injector</TT></A>, should one exist. |
| |
| <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<T>)"></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<T>)</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<T>)"></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<T>)</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<T>)"></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<T> <b>getProvider(Class<T>)</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.</span></blockquote> |
| <A NAME="com.google.inject.Injector.dmethod.getProvider(Key<T>)"></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<T> <b>getProvider(Key<T>)</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.</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 performs this injection automatically (after first |
| </span> <span style="background: #FFFF00">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>.</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="../v2/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 crazybob@google.com (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="../v2/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="../v2/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="../v2/com/google/inject/Module/.html#configure"><TT>.configure</TT></A>, bindings |
| will be created for all methods annotated with {@literal @}<A HREF="../v2/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 <span style="background: #FFFF00">for this module </span>to a {@code Binder}.<span style="background: #FFFF00"> |
| |
| <p><strong>Do not invoke this method directly</strong> to install submodules. Instead use |
| <A HREF="../v2/Binder.html#install(Module)"><TT>Binder.install(Module)</TT></A>, which ensures that <A HREF="../v2/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</strike><span style="background: #FFFF00">will</span> <strike>they are</strike><span style="background: #FFFF00">be</span> <strike>absolutely needed</strike><span style="background: #FFFF00">initialized lazily</span>. |
| |
| <li>A custom <A HREF="../v2/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="../v2/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="../v2/com/google/inject/Provider/Injector.html#getProvider"><TT>Injector.getProvider</TT></A><strike> |
| </strike> methods. |
| </ul> |
| |
| @param <T> the type of object this provider provides |
| |
| @author crazybob@google.com (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="../v2/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="../v2/com/google/inject/Scope/Scopes.html#SINGLETON"><TT>Scopes<strike>#SINGLETON |
| |
| </strike><span style="background: #FFFF00">.SINGLETON</TT></A>. |
| |
| </span> @author crazybob@google.com (Bob Lee)</blockquote> |
| <A NAME="com.google.inject.Scope.dmethod.scope(Key<T>, Provider<T>)"></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<T> <b>scope(Key<T>, Provider<T>)</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="../v2/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.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>Assumes that type {@code T} implements <A HREF="../v2/com/google/inject/TypeLiteral/Object.html#equals"><TT>Object.equals</TT></A> and |
| <A HREF="../v2/com/google/inject/TypeLiteral/Object.html#hashCode()"><TT>Object.hashCode()</TT></A> as value (as opposed to identity) comparison. |
| |
| @author crazybob@google.com (Bob Lee)<span style="background: #FFFF00"> |
| @author jessewilson@google.com (Jesse Wilson)</span></blockquote> |
| <hr align="left" width="100%"> |
| |
| </BODY> |
| </HTML> |