blob: 0650149fcbbbf0c444043384e174e1e4eb77ca3e [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN""http://www.w3.org/TR/REC-html40/frameset.dtd">
<HTML>
<HEAD>
<meta name="generator" content="JDiff v1.1.1">
<!-- Generated by the JDiff Javadoc doclet -->
<!-- (http://www.jdiff.org) -->
<meta name="description" content="JDiff is a Javadoc doclet which generates an HTML report of all the packages, classes, constructors, methods, and fields which have been removed, added or changed in any way, including their documentation, when two APIs are compared.">
<meta name="keywords" content="diff, jdiff, javadiff, java diff, java difference, API difference, difference between two APIs, API diff, Javadoc, doclet">
<LINK REL="stylesheet" TYPE="text/css" HREF="../stylesheet-jdiff.css" TITLE="Style">
<TITLE>
com.google.inject Documentation Differences
</TITLE>
</HEAD>
<BODY>
<!-- Start of nav bar -->
<TABLE summary="Navigation bar" BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<TABLE summary="Navigation bar" BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/package-summary.html" target="_top"><FONT CLASS="NavBarFont1"><B><tt>3.0</tt></B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="changes-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> &nbsp;<FONT CLASS="NavBarFont1">Package</FONT>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1"> &nbsp;<FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="docdiffs_index.html"><FONT CLASS="NavBarFont1"><B>Text Changes</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_statistics.html"><FONT CLASS="NavBarFont1"><B>Statistics</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="jdiff_help.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM><b>Generated by<br><a href="http://www.jdiff.org" class="staysblack" target="_top">JDiff</a></b></EM></TD>
</TR>
<TR>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell2"><FONT SIZE="-2">
<B>PREV PACKAGE</B> &nbsp;
&nbsp;<A HREF="docdiffs_com.google.inject.assistedinject.html"><B>NEXT PACKAGE</B></A>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<A HREF="../changes.html" TARGET="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="docdiffs_com.google.inject.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell2">&nbsp;</TD>
</TR>
</TABLE>
<HR>
<!-- End of nav bar -->
<h2>
com.google.inject Documentation Differences
</h2>
<blockquote>
This file contains all the changes in documentation in the package <code>com.google.inject</code> as colored differences.
Deletions are shown <strike>like this</strike>, and
additions are shown <span style="background: #FFFF00">like this</span>.
</blockquote>
<blockquote>
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The <i>new</i> HTML tags are shown in the differences.
If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here.
Similarly, documentation which was inherited from another class or interface is not shown here.
</blockquote>
<blockquote>
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a &lt;code&gt; tag will cause all subsequent paragraphs to be displayed differently.
</blockquote>
<hr>
<A NAME="com.google.inject.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/3.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/3.0/javadoc/com/google/inject/Binder/Module.html"><TT>Module</TT></A> implementors so they may each contribute
their own bindings and other registrations.
<h3>The Guice Binding EDSL</h3>
Guice uses an <i>embedded domain-specific language</i>, or EDSL, to help you
create bindings 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 by reading
method-level javadocs</b>. Instead, you should consult the series of
examples below. To save space, these examples omit the opening
{@code binder}, just as you will if your module extends
<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/AbstractModule.html"><TT>AbstractModule</TT></A>.
<pre>
bind(ServiceImpl.class);</pre>
This statement does essentially nothing; it "binds the {@code ServiceImpl}
class to itself" and does not change Guice's default behavior. You may still
want to use this if you prefer your <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Module.html"><TT>Module</TT></A> class to serve as an
explicit <i>manifest</i> for the services it provides. Also, in rare cases,
Guice may be unable to validate a binding at injector creation time unless it
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 a 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/3.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/3.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 binding specifies that Guice should resolve
an unannotated injection request for {@code 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/3.0/javadoc/com/google/inject/Binder/Provider.html#get"><TT>get()</TT></A> on the resulting Provider instance to obtain the
{@code Service} instance.
<p>The <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Provider.html"><TT>Provider</TT></A> you use here does not have to be a "factory"; that
is, a provider which always <i>creates</i> each instance it provides.
However, this is generally a good practice to follow. You can then use
Guice's concept of <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Scope.html"><TT>scopes</TT></A> to guide when creation should happen
-- "letting Guice work for you".
<pre>
bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);</pre>
Like the previous example, but only applies to injection requests that use
the binding annotation {@code @Red}. If your module also includes bindings
for particular <i>values</i> of the {@code @Red} annotation (see below),
then this binding will serve as a "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 it for all injection requests of this type. Note that it is
still possible to bind another instance of {@code ServiceImpl} if the second
binding is qualified by an annotation as in the 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/3.0/javadoc/com/google/inject/Binder/Singleton.html"><TT>Singleton</TT></A>/<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.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 can
contribute their own custom scopes for use here as well.
<pre>
bind(new TypeLiteral&lt;PaymentService&lt;CreditCard>>() {})
.to(CreditCardPaymentService.class);</pre>
This admittedly odd construct is the way to bind a parameterized type. It
tells Guice how to honor an injection request for an element of type
{@code PaymentService<CreditCard>}. The class
{@code CreditCardPaymentService} must implement the
{@code PaymentService<CreditCard>} interface. Guice cannot currently bind or
inject a generic type, 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. When
the <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Injector.html"><TT>Injector</TT></A> is created, it will automatically perform field
and method injection for this instance, but any injectable constructor on
{@code ServiceImpl} is simply ignored. Note that using this approach results
in "eager loading" behavior that you can't control.
<pre>
bindConstant().annotatedWith(ServerHost.class).to(args[0]);</pre>
Sets up a constant binding. Constant injections must always be annotated.
When a constant binding's value is a string, it is eligile for conversion to
all primitive types, to <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Enum.html#valueOf(Class, String)"><TT>all enums</TT></A>, and to
<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.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/3.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").getAnnotation(Color.class);
bind(Service.class).annotatedWith(red).to(RedService.class);</pre>
If your binding annotation has parameters you can apply different bindings to
different specific values of your annotation. Getting your hands on the
right instance of the annotation is a bit of a pain -- one approach, 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"))
.to(BlueService.class);</pre>
Differentiating by names is a common enough use case that we provided a
standard annotation, <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.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 binding annotation case we just saw. However, remember that these
names will live in a single flat namespace with all the other names used in
your application.
<pre><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 need to place {@literal @}Inject
on any of the constructors and 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 simpler than using a <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/Provider.html"><TT>Provider</TT></A>.
</span><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="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#bindScope"><TT>.bindScope</TT></A>,
<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#bindInterceptor"><TT>.bindInterceptor</TT></A>, <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#install"><TT>.install</TT></A>, <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#requestStaticInjection"><TT>.requestStaticInjection</TT></A>,
<A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#addError"><TT>.addError</TT></A> and <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/com/google/inject/Binder/.html#currentStage"><TT>.currentStage</TT></A> are not part of the Binding EDSL;
you can learn how to use these in the usual way, from the method
documentation.
@author crazybob@google.com (Bob Lee)
@author jessewilson@google.com (Jesse Wilson)
@author kevinb@google.com (Kevin Bourrillion)</blockquote>
<A NAME="com.google.inject.Binder.dmethod.getProvider(Key&lt;T&gt;)"></A><a href="com.google.inject.Binder.html" class="hiddenlink">Class <b>Binder</b></a>, <a href="com.google.inject.Binder.html#com.google.inject.Binder.getProvider_changed(com.google.inject.Key<T>)" class="hiddenlink">Provider&lt;T&gt; <b>getProvider(Key&lt;T&gt;)</b></a><br><br><blockquote>Returns the provider used to obtain instances for the given injection key.
The returned <span style="background: #FFFF00">provider </span>will not be valid until the <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/Injector.html"><TT>Injector</TT></A> has been
created. The provider will throw an {@code IllegalStateException} if you
try to use it beforehand.
@since 2.0</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/3.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/3.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/3.0/javadoc/com/google/inject/Guice/InjectorBuilder.html"><TT>InjectorBuilder</TT></A>.</span>
<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></blockquote>
<A NAME="com.google.inject.Guice.dmethod.createInjector(Iterable&lt;Module&gt;)"></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(java.lang.Iterable<? extends com.google.inject.Module>)" class="hiddenlink">Injector <b>createInjector(Iterable&lt;Module&gt;)</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/3.0/javadoc/Stage.html"><TT>Stage</TT></A> or other options, see <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A>.</span>
@throws CreationException if one or more errors occur during <strike>Injector
</strike><span style="background: #FFFF00">injector
</span> creation</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/3.0/javadoc/Stage.html"><TT>Stage</TT></A> or other options, see <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A>.</span>
@throws CreationException if one or more errors occur during <strike>Injector
</strike><span style="background: #FFFF00">injector
</span> construction</blockquote>
<A NAME="com.google.inject.Guice.dmethod.createInjector(Stage, Iterable&lt;Module&gt;)"></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, java.lang.Iterable<? extends com.google.inject.Module>)" class="hiddenlink">Injector <b>createInjector(Stage, Iterable&lt;Module&gt;)</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/3.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A> for advanced injector creation.</span>
@throws CreationException if one or more errors occur during <strike>Injector
</strike><span style="background: #FFFF00">injector
</span> construction</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/3.0/javadoc/InjectorBuilder.html"><TT>InjectorBuilder</TT></A> for advanced injector creation.</span>
@throws CreationException if one or more errors occur during <strike>Injector
</strike><span style="background: #FFFF00">injector
</span> creation<span style="background: #FFFF00">.</span></blockquote>
<hr align="left" width="100%">
<A NAME="com.google.inject.Injector.dmethod.getBindings()"></A><a href="com.google.inject.Injector.html" class="hiddenlink">Class <b>Injector</b></a>, <a href="com.google.inject.Injector.html#com.google.inject.Injector.getBindings_changed()" class="hiddenlink">Map&lt;Key&lt;?&gt;, Binding&lt;?&gt;&gt; <b>getBindings()</b></a><br><br><blockquote>Returns <strike>all</strike><span style="background: #FFFF00">this</span> <span style="background: #FFFF00">injector's <strong></span>explicit</strong> bindings.
<p>The returned map does not include bindings inherited from a <A HREF="http://google-guice.googlecode.com/svn/trunk/latest-api-diffs/3.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/3.0/javadoc/Map.html#entrySet()"><TT><strike>java.util.</strike>Map.entrySet()</TT></A> iterator) in the order of insertion. In other words,<strike>
</strike> the order <strike>in</strike><span style="background: #FFFF00">in
</span> which bindings appear in user Modules.
<p>This method is part of the Guice SPI and is intended for use by tools and extensions.</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%">
</BODY>
</HTML>