| <!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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/package-summary.html" target="_top"><FONT CLASS="NavBarFont1"><B><tt>2.0</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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/AbstractModule/.html#configure()"><TT>.configure()</TT></A>, and call the inherited methods which mirror those found in |
| <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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 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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A>. Guice provides this object to your |
| application's <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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</span> <span style="background: #FFFF00">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 module extends |
| <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/AbstractModule.html"><TT>AbstractModule</TT></A>. |
| |
| </span> <pre><span style="background: #FFFF00"> |
| 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</span> <span style="background: #FFFF00">this if you prefer your <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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</span> <i><span style="background: #FFFF00">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 unless it |
| is given explicitly. |
| |
| <pre> |
| bind(Service.class).to(ServiceImpl.class);</pre> |
| |
| Specifies that</span> <strike>uniquely</strike><span style="background: #FFFF00">a request for a {@code Service} instance with no</span> <strike>identifies</strike><span style="background: #FFFF00">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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/ImplementedBy.html"><TT>@ImplementedBy</TT></A> or <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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 not</span> <strike>key</strike><span style="background: #FFFF00">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 is</strike><span style="background: #FFFF00">concept of</span> <strike>now</strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Scope.html"><TT><span style="background: #FFFF00">scopes</TT></A> to guide when creation 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</span> <strike>references</strike><span style="background: #FFFF00">will serve as</span> a <strike>Provider</strike><span style="background: #FFFF00">"catch-all" for any values of {@code @Red} |
| that have no exact match in the bindings. |
| |
| <pre> |
| bind(ServiceImpl.class).in(Singleton.class); |
| // or, alternatively |
| bind(ServiceImpl.class).in(Scopes.SINGLETON);</pre> |
| |
| Either of these statements places the {@code ServiceImpl} class into |
| singleton scope. Guice will create only one instance of {@code ServiceImpl} |
| and will reuse</span> <span style="background: #FFFF00">it </span>for <span style="background: #FFFF00">all injection requests of </span>this <strike>key |
| </strike><span style="background: #FFFF00">type. </span> <strike>A</strike><span style="background: #FFFF00">Note</span> <strike>preconstructed instance |
| </strike><span style="background: #FFFF00">that it</span> <strike>A</strike><span style="background: #FFFF00">is |
| </span> <strike>preconstructed</strike><span style="background: #FFFF00">still</span> <span style="background: #FFFF00">possible to bind another </span>instance <strike>which</strike><span style="background: #FFFF00">of</span> <strike>should</strike><span style="background: #FFFF00">{@code</span> <strike>be</strike><span style="background: #FFFF00">ServiceImpl}</span> <strike>used</strike><span style="background: #FFFF00">if the second |
| binding is qualified by an annotation</span> as <span style="background: #FFFF00">in </span>the <span style="background: #FFFF00">previous example. Guice is |
| not overly concerned with <i>preventing</i> you from creating multiple |
| instances of your "singletons", 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 specified in this way <i>overrides</i> any scope that |
| was specified with an annotation on the {@code ServiceImpl} class. |
| |
| <p>Besides <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Singleton.html"></span><TT><strike>Provider</strike><span style="background: #FFFF00">Singleton</span></TT></A><strike> |
| </strike><span style="background: #FFFF00">/<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Scopes.html#SINGLETON"><TT>Scopes.SINGLETON</TT></A>, there are |
| servlet-specific scopes available in |
| {@code com.google.inject.servlet.ServletScopes}, and your Modules</span> <span style="background: #FFFF00">can |
| </span> <span style="background: #FFFF00">contribute</span> <span style="background: #FFFF00">their own custom scopes </span>for <strike>this binding |
| </strike><span style="background: #FFFF00">use here</span> <span style="background: #FFFF00">as well.</span> |
| |
| <strike>In</strike><pre><span style="background: #FFFF00"> |
| </span> <strike>addition,</strike><span style="background: #FFFF00"> bind(new TypeLiteral<PaymentService<CreditCard>>() {}) |
| .to(CreditCardPaymentService.class);</pre> |
| |
| This admittedly odd construct is the way to bind</span> a <strike>binding</strike><span style="background: #FFFF00">parameterized</span> <strike>may</strike><span style="background: #FFFF00">type.</span> <strike>have</strike><span style="background: #FFFF00">It |
| tells Guice how to honor</span> an <strike>associated</strike><span style="background: #FFFF00">injection</span> <strike>scope</strike><span style="background: #FFFF00">request for an element of type |
| {@code PaymentService<CreditCard>}. The class |
| {@code CreditCardPaymentService} must implement the |
| {@code PaymentService<CreditCard>} interface. Guice cannot currently bind or |
| inject a generic type</span>, such <strike>as |
| </strike><span style="background: #FFFF00">as</span> <strike>Scopes</strike><span style="background: #FFFF00">{@code Set<E>}; all type parameters must be |
| fully specified</span>.<strike>SINGLETON</strike><span style="background: #FFFF00"> |
| |
| <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. When |
| the <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Injector.html"><TT>Injector</span></TT></A><span style="background: #FFFF00"> is created</span>, <span style="background: #FFFF00">it will automatically perform field |
| </span>and <strike>singleton bindings</strike><span style="background: #FFFF00">method injection</span> <strike>may</strike><span style="background: #FFFF00">for this instance, but any injectable constructor on |
| {@code ServiceImpl} is simply ignored.</span> <strike>specify</strike> <span style="background: #FFFF00">Note that using this approach results |
| in "</span>eager <strike>or</strike><span style="background: #FFFF00">loading" behavior that you</span> <strike>lazy |
| </strike><span style="background: #FFFF00">can't</span> <strike>initialization</strike><span style="background: #FFFF00">control</span>. |
| |
| <strike>See</strike><pre><span style="background: #FFFF00"> |
| </span> <strike>the</strike><span style="background: #FFFF00"> bindConstant().annotatedWith(ServerHost.class).to(args[0]);</pre> |
| |
| Sets up a constant binding. Constant injections must always be annotated. |
| When a constant</span> <strike>users</strike><span style="background: #FFFF00">binding</span>'<span style="background: #FFFF00">s</span> <strike>guide</strike><span style="background: #FFFF00">value is a string, it is eligile for conversion to |
| all primitive types, to</span> <strike>appendix</strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Enum.html#valueOf(Class, String)"><TT><span style="background: #FFFF00">all enums</TT></A></span>, <span style="background: #FFFF00">and to |
| <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Class.html#forName"><TT>class literals</TT></A>. Conversions for other types can be |
| configured using <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#convertToTypes(Matcher, TypeConverter)"><TT> convertToTypes()</TT></A>. |
| |
| <pre> |
| {@literal @}Color("red") Color red; // A member variable (field) |
| . . . |
| red = MyModule.class.getDeclaredField("red</span>"<strike>How</strike><span style="background: #FFFF00">).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</span> <span style="background: #FFFF00">annotation. Getting your hands on the |
| right instance of </span>the <strike>Injector resolves injection |
| </strike><span style="background: #FFFF00">annotation is a</span> <strike>requests</strike><span style="background: #FFFF00">bit of a pain -- one approach, shown |
| above, is to apply a prototype annotation to a field in your module class</span>,<span style="background: #FFFF00"> so |
| that you can read this annotation instance and give it to Guice. |
| |
| <pre> |
| bind(Service.class) |
| .annotatedWith(Names.named(</span>"<span style="background: #FFFF00">blue")) |
| </span> <span style="background: #FFFF00"> .</span>to<span style="background: #FFFF00">(BlueService.class);</pre> |
| |
| Differentiating by names is a</span> <strike>better understand</strike><span style="background: #FFFF00">common enough</span> <span style="background: #FFFF00">use case that we provided a |
| standard annotation, <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/com/google/inject/name/Named.html"><TT>@Named</TT></A>. Because of |
| Guice's library support, binding by name is quite easier than in the |
| arbitrary </span>binding <strike>resolution</strike><span style="background: #FFFF00">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</span>. |
| |
| <strike>After</strike><pre><span style="background: #FFFF00"> |
| </span> <strike>an</strike><span style="background: #FFFF00"> Constructor<T> loneCtor = getLoneCtorFromServiceImplViaReflection(); |
| bind(ServiceImpl.class) |
| .toConstructor(loneCtor);</pre> |
| |
| In this example, we directly tell Guice which constructor to use in a concrete |
| class implementation. It means that we do not</span> <span style="background: #FFFF00">need to place </span>{@<strike>code Injector</strike><span style="background: #FFFF00">literal @</span>}<span style="background: #FFFF00">Inject |
| </span> <strike>has been</strike><span style="background: #FFFF00">on any</span> <strike>created,</strike><span style="background: #FFFF00">of</span> <strike>its bindings may</strike><span style="background: #FFFF00">the constructors and</span> <strike>be |
| </strike><span style="background: #FFFF00">that Guice treats the provided constructor as though |
| it were annotated so. It is useful for cases where you cannot modify existing |
| classes and is a bit</span> <strike>examined</strike><span style="background: #FFFF00">simpler</span> <span style="background: #FFFF00">than </span>using <span style="background: #FFFF00">a <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/Provider.html"><TT>Provider</TT></A>. |
| |
| <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 </span>methods <strike>like</strike><span style="background: #FFFF00">of Binder</span> <span style="background: #FFFF00">such as <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#bindScope"></span><TT><strike>Injector</strike>.<strike>getBinding(Key)</strike><span style="background: #FFFF00">bindScope</span></TT></A>,<span style="background: #FFFF00"> |
| </span> <strike>but</strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#bindInterceptor"><TT><span style="background: #FFFF00">.bindInterceptor</TT></A>,</span> <strike>this |
| </strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#install"><TT><span style="background: #FFFF00">.install</TT></A>,</span> <strike>read-only</strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#requestStaticInjection"><TT><span style="background: #FFFF00">.requestStaticInjection</TT></A>, |
| </span> <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#addError"><TT><strike>Binding</strike><span style="background: #FFFF00">.addError</span></TT></A> <strike>type</strike><span style="background: #FFFF00">and</span> <strike>is</strike><A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binder/.html#currentStage"><TT><span style="background: #FFFF00">.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.com (Bob Lee) |
| @author jessewilson@google.com (Jesse Wilson) |
| @author kevinb@google</span>.<span style="background: #FFFF00">com (Kevin Bourrillion)</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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/Binder.html"><TT><span style="background: #FFFF00">Binder</TT></A></span>.</blockquote>
|
| <A NAME="com.google.inject.Binder.dmethod.bindInterceptor(Matcher<Class<?>>, Matcher<Method>, 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<Class<?>>, Matcher<Method>, 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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binding/ImplementedBy.html"><TT> pointer</TT></A> <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Binding/ProvidedBy.html"><TT>annotations</TT></A> or by using its <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/Binding.html"><TT>Binding</TT></A> |
| created via <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/spi/Elements.html#getElements"><TT>com.google.inject.spi.Elements.getElements</TT></A>. This |
| method is only supported on <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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(Collection<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.util.Collection<com.google.inject.spi.Message>)" class="hiddenlink">constructor <b>CreationException(Collection<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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Guice/Injector.html"><TT>Injector</TT></A>s from |
| <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Guice/Module.html"><TT>Module</TT></A>s.<span style="background: #FFFF00"> For advanced usage, see <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Guice/InjectorBuilder.html"><TT>InjectorBuilder</TT></A>. |
| |
| <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.<span style="background: #FFFF00"> To create an injector |
| with a <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/Stage.html"><TT>Stage</TT></A> or other options, see <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A>.</span> |
| |
| @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.<span style="background: #FFFF00"> Use <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A> for advanced injector creation.</span> |
| |
| @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">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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Injector/Guice.html"><TT>Guice</TT></A>. |
| |
| <p><span style="background: #FFFF00">An injector can also <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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)<span style="background: #FFFF00"> |
| @author jessewilson@google.com (Jesse Wilson)</span></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 all</strike><span style="background: #FFFF00">Returns this</span> <span style="background: #FFFF00">injector's <strong></span>explicit</strong><span style="background: #FFFF00"> bindings. |
| |
| <p>The returned map does not include bindings inherited from a <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/.html#getParent()"><TT>parent |
| injector</TT></A>, should one exist. The returned map is guaranteed to iterate (for example, with |
| its <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/Map.html#entrySet()"><TT>Map.entrySet()</TT></A> iterator)</span> <span style="background: #FFFF00">in the order of insertion. In other words, the order in |
| which </span>bindings<span style="background: #FFFF00"> 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<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. |
| @see Binder#getProvider(Class) for an alternative that offers up front error detection</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. |
| @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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/com/google/inject/Module/.html#configure"><TT>.configure</TT></A>, bindings |
| will be created for all methods annotated with {@literal @}<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/Binder.html#install(Module)"><TT>Binder.install(Module)</TT></A>, which ensures that <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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 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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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.ScopeAnnotation!class"></A><a href="com.google.inject.ScopeAnnotation.html" class="hiddenlink">Class <b>ScopeAnnotation</b></a><br><br><blockquote>Annotates annotations which are used for scoping. Only one such annotation |
| may apply to a single implementation class. You must also annotate scope |
| annotations with {@code @Retention(RUNTIME)}. For example: |
| |
| <pre> |
| {@code @}Retention(RUNTIME) |
| {@code @}Target(TYPE<span style="background: #FFFF00">, METHOD</span>) |
| {@code @}ScopeAnnotation |
| public {@code @}interface SessionScoped {} |
| </pre> |
| |
| @author crazybob@google.com (Bob Lee)</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 crazybob@google.com (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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/2.0/javadoc/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 crazybob@google.com (Bob Lee)<span style="background: #FFFF00"> |
| @author jessewilson@google.com (Jesse Wilson)</span></blockquote>
|
| <hr align="left" width="100%">
|
|
|
| </BODY>
|
| </HTML>
|
