4.2  Overview   Package   Class  Text Changes  Statistics  Help 
Generated by
JDiff
PREV PACKAGE    NEXT PACKAGE          FRAMES    NO FRAMES  

com.google.inject.spi Documentation Differences

This file contains all the changes in documentation in the package com.google.inject.spi as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.
Class BindingScopingVisitor

Visits each of the strategies used to scope an injection. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @since 2.0
Class BindingScopingVisitor, V visitNoScoping()

Visit an unspecified or unscoped strategy. On a module, this strategy indicates that the injector should use scoping annotations to find a scope. On an injector, it indicates that nothat no scope is applied to the binding. An unscoped binding will behave like a scoped one when it it isis linked to a scoped binding.
Class BindingTargetVisitor

Visits each of the strategies used to find an instance to satisfy an injection. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @since 2.0
Class BindingTargetVisitor, V visit(ConvertedConstantBinding<? extends T>)

Visit a binding created from converting a bound instance to a new type. The source binding hasbinding has the same binding annotation but a different type. This target is found only on injector bindings.
Class BindingTargetVisitor, V visit(LinkedKeyBinding<? extends T>)

Visit a linked key binding. The other key's binding is used to resolve injections. This targetThis target is found in both module and injector bindings.
Class BindingTargetVisitor, V visit(UntargettedBinding<? extends T>)

Visit an untargetted binding. This target is found only on module bindings. It indicates thatindicates that the injector should use its implicit binding strategies to resolve injections.
Class ConstructorBinding, Set<InjectionPoint> getInjectableMembers()

Returns all instance method and field injection points on {@code type}. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods.
Class ConvertedConstantBinding, TypeConverterBinding getTypeConverterBinding()

Returns the type converter binding used to convert the constant. @since 3.0
Class DefaultBindingScopingVisitor

No-op visitor for subclassing. All interface methods simply delegate to to .visitOther(), returning its result. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @author jessewilson@google.com (Jesse Wilson) @since 2.0
Class DefaultBindingTargetVisitor

No-op visitor for subclassing. All interface methods simply delegate to .visitOther(Binding), returning its result. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @author jessewilson@google.com (Jesse Wilson) @since 2.0
Class DefaultElementVisitor

No-op visitor for subclassing. All interface methods simply delegate to to .visitOther(Element), returning its result. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @author sberlin@gmail.com (Sam Berlin) @since 2.0
Class DependencyAndSource

A combination of a Dependency and the source where thethe dependency was bound. @author sameb@google.com (Sam Berlin) @since 4.00 @deprecated The only use of this object is for ProvisionListener.ProvisionInvocation.getDependencyChain() which is also deprecated. This object will also be removed in Guice 4.4.
Class DependencyAndSource, String getBindingSource()

Returns a string describing where this dependency was bound. If the binding binding was just-in-time, there is no valid binding source, so this describes the the class in question.
Class DependencyAndSource, Dependency<?> getDependency()

Returns the Dependency, if one exists. For anything that can be referenced referenced by Injector.getBinding, a dependency exists. A dependency will not not exist (and this will returnreturn null) for types initialized with with Binder.requestInjection or Injector.injectMembers(Object), nor will it exist for objects injected into Providers bound with bound with LinkedBindingBuilder#toProvider(Provider).
Class ElementSource

Contains information about where and how an element was was bound.

The declaring source refers to a location in in source code thatthat defines the Guice element. For example, if if the element is created from a methodmethod annotated by {@literal @Provides}, the the declaring source of element would be the method itself.

The .getStackTrace() refers to the sequence of calls ends at one of of com.google.inject.Binder {@code bindXXX()} methods and eventually eventually defines the element. Note thatthat .getStackTrace() lists lists StackTraceElements in reversereverse chronological order. The first element (index zero) is the last method call and the last element is the first method invocation. By default, the stack trace is not collected. The defaultdefault behavior can be changed by setting the the {@code guice_include_stack_traces} flag value. The valuevalue can be either either {@code OFF}, {@code ONLY_FOR_DECLARING_SOURCE} or {@code COMPLETE}. Note that collecting stack traces for every binding can cause a performance hit when when the injector isis created.

The sequence of class names of modules involved in thethe element creation can be retrieved by by .getModuleClassNames(). Similar to .getStackTrace(), the the order is reverse chronological. The first module (index 0) is the modulemodule that that installs the element. The last module is the root module.

In order to support the cases where a Guice element is is created from anotheranother Guice element (original) (e.g., by by Element.applyTo), it also provides aa reference to the original original element source (.getOriginalElementSource()). @since 4.0

Class ElementSource, Object getDeclaringSource()

Returns a single location in source code that defines the element. It can be any object object such asas java.lang.reflect.Constructor, java.lang.reflect.Method, java.lang.reflect.Field, StackTraceElement, etc. For For example, if the element isis created from a method annotated by {@literal @Provides}, the the declaring source of element wouldwould be the method itself.
Class ElementSource, List<String> getModuleClassNames()

Returns the class names of modules involved in creating this Element. The first elementfirst element (index 0) is the class name of module that defined the element, and the last element element is thethe class name of root module.
Class ElementSource, List<Integer> getModuleConfigurePositionsInStackTrace()

Returns the position of configure(Binder) method call in the stack trace for modules that their classes returned by .getModuleClassNames. For example, if the stack trace looks like the following:
    {@code 0 -
  1. {@code Binder.bind(),} 1 -
  2. {@code ModuleTwo.configure(),} 2 -
  3. {@code Binder.install(),} 3 -
  4. {@code ModuleOne.configure(),} 4 -
  5. {@code theRest(). }

1 and 3 are returned.

In the cases where stack trace is not available (i.e., the stack trace was not collected), it returns -1 for all module positions.

Class ElementSource, StackTraceElement[] getStackTrace()

Returns the sequence of method calls that ends at one of com.google.inject.Binder {@code bindXXX()} methods and eventually defines the element. Note that that .getStackTrace lists StackTraceElements in reverse reverse chronological order. The firstfirst element (index zero) is the last method call and the last last element is the first methodmethod invocation. In the cases where stack trace is not available available (i.e.,the stack trace was notnot collected), it returns an empty array.
Class ElementVisitor

Visit elements. @param any type to be returned by the visit method. Use Void with with {@code return null} if no return type is needed. @since 2.0
Class ElementVisitor, V visit(Binding<T>)

Visit a mapping from a key (type and optional annotation) to the strategy for getting instancesgetting instances of the type.
Class ElementVisitor, V visit(DisableCircularProxiesOption)

Visit a disable circular proxies command. @since 3.0
Class ElementVisitor, V visit(RequireAtInjectOnConstructorsOption)

Visit a require explicit {@literal @}Inject command. @since 4.0
Class ElementVisitor, V visit(RequireExplicitBindingsOption)

Visit a require explicit bindings command. @since 3.0
Class HasDependencies, Set<Dependency<?>> getDependencies()

Returns the known dependencies for this type. If this has dependencies whose values are not known statically, a dependency for the Injector will be included in the returned set. @return a possibly empty set
Class InjectionPoint, InjectionPoint forConstructor(Constructor<T>)

Returns a new injection point for the specified constructor. If the declaring type of {@code constructor} is parameterized (such as {@code List}), prefer the overload that includes a type literal. @param constructor any single constructor present on {@code type}. @since 3.0
Class InjectionPoint, InjectionPoint forConstructor(Constructor<T>, TypeLiteral<? extends T>)

Returns a new injection point for the specified constructor of {@code type}. @param constructor any single constructor present on {@code type}. @param type the concrete type that defines {@code constructor}. @since 3.0
Class InjectionPoint, Set<InjectionPoint> forInstanceMethodsAndFields(Class<?>)

Returns all instance method and field injection points on {@code type}. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on {@code type}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class InjectionPoint, Set<InjectionPoint> forInstanceMethodsAndFields(TypeLiteral<?>)

Returns all instance method and field injection points on {@code type}. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on {@code type}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class InjectionPoint, InjectionPoint forMethod(Method, TypeLiteral<T>)

Returns a new injection point for the specified method of {@code type}. This is useful forfor extensions that need to build dependency graphs from from arbitrary methods. @param method any single method present on {@code type}. @param type the concrete type that defines {@code method}. @since 4.0
Class InjectionPoint, Set<InjectionPoint> forStaticMethodsAndFields(Class<?>)

Returns all static method and field injection points on {@code type}. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on {@code type}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class InjectionPoint, Set<InjectionPoint> forStaticMethodsAndFields(TypeLiteral<?>)

Returns all static method and field injection points on {@code type}. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on {@code type}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class InjectionPoint, TypeLiteral<?> getDeclaringType()

Returns the generic type that defines this injection point. If the member exists on a parameterized type, the result will include more type information than the member's raw declaring class. @since 3.0
Class InjectionPoint, boolean isToolable()

Returns true if the element is annotated with {@literal @}Toolable. @since 3.0
Class InjectionRequest

A request to inject the instance fields and methods of an instance. Requests are created explicitly in a module using requestInjection() statements: 
     requestInjection(serviceInstance);
@author mikeward@google.com (Mike Ward) @since 2.0
Class InjectionRequest, Set<InjectionPoint> getInjectionPoints()

Returns the instance methods and fields of {@code instance} that will be injected to fulfill this request. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on the class of {@code instance}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class InterceptorBinding

Registration of interceptors for matching methods of matching classes. Instances are created explicitly in a module using bindInterceptor() statements: 
     bindInterceptor(Matchers.subclassesOf(MyAction.class),
         Matchers.annotatedWith(Transactional.class),
         new MyTransactionInterceptor());
or from an injectable type listener using TypeEncounter.bindInterceptor(). @author jessewilson@google.com (Jesse Wilson) @since 2.0
Class MembersInjectorLookup

A lookup of the members injector for a type. Lookups are created explicitly in a module using getMembersInjector() statements: 
     MembersInjector<PaymentService> membersInjector
         = getMembersInjector(PaymentService.class);
@author crazybob@google.com (Bob Lee) @since 2.0
Class MembersInjectorLookup, MembersInjector<T> getDelegate()

Returns the delegate members injector, or {@code null} if it has not yet been initialized. TheThe delegate will be initialized when this element is processed, or otherwise used to create create anan injector.
Class Message

An error message and the context in which it occured. Messages are usually created internally by Guice and its extensions. Messages can be created explicitly in a module using addError() statements: 
     try {
       bindPropertiesFromFile();
     } catch (IOException e) {
       addError(e);
     }
@author crazybob@google.com (Bob Lee)
Class Message, Throwable getCause()

Returns the throwable that caused this message, or {@code null} if this this message was not causedcaused by a throwable. @since 2.0
Class ModuleAnnotatedMethodScanner

Allows extensions to scan modules for annotated methods and bind those methods methods as providers, similar to {@code @Provides} methods. @since 4.0
Class ModuleAnnotatedMethodScanner, Key<T> prepareMethod(Binder, Annotation, Key<T>, InjectionPoint)

Prepares a method for binding. This {@code key} parameter is the key discovered from looking at the binding annotation and return value of the method. Implementations can modify the key to instead bind to another key. For example, Multibinder may want to change change {@code @SetProvidesSetProvides String provideFoo()} to bind into a unique Key within the multibinder multibinder instead of binding {@codecode String}.

The injection point and annotation are provided in case the implementation wants to set the key based on the property of the annotation or if any additional preparation is needed for any of the dependencies. The annotation is guaranteed to be an instance of one the classes returned by .annotationClasses.

Class ModuleAnnotatedMethodScannerBinding

Represents a call to Binder.scanModulesForAnnotatedMethods in a module. @author sameb@google.com (Sam Berlin) @since 4.0
Class ProviderInstanceBinding, Provider<? extends T> getProviderInstance()

If the user supplied a JSR330 binding, then this will wrap that one. To always return the user-supplied provider, use .getUserSuppliedProvider. @deprecated Use .getUserSuppliedProvider instead.
Class ProviderInstanceBinding, Provider<? extends T> getUserSuppliedProvider()

Returns the user-supplied, unscoped provider. @since 4.0
Class ProviderLookup

A lookup of the provider for a type. Lookups are created explicitly in a module using using getProvider() statements: 
     Provider<PaymentService> paymentServiceProvider
         = getProvider(PaymentService.class);
@author jessewilson@google.com (Jesse Wilson) @since 2.0
Class ProviderWithExtensionVisitor

A Provider that is part of an extension which supports a custom custom BindingTargetVisitor.

When an extension binds a provider instance, the provider can implement this this interface toto allow users using the the Binding.acceptTargetVisitor(BindingTargetVisitor) method to visit a custom visitor designed for that extension. A typical implementation within within the extension wouldwould look like like 

 
 <V, B> V acceptExtensionVisitor(BindingTargetVisitor<B, V> visitor, ProviderInstanceBinding<? extends B> binding) {
   if(visitor instanceof MyCustomExtensionVisitor) {
     return ((MyCustomExtensionVisitor<B, V>)visitor).visitCustomExtension(customProperties, binding);
   } else {
     return visitor.visit(binding);
   }
 }
'MyCustomExtensionVisitor' in the example above would be an interface the the extension provides thatthat users can implement in order to be notified of custom custom extension information. These visitorvisitor interfaces must extend from from BindingTargetVisitor. @since 3.0 @author sameb@google.com (Sam Berlin)
Class ProviderWithExtensionVisitor, V acceptExtensionVisitor(BindingTargetVisitor<B, V>, ProviderInstanceBinding<? extends B>)

Instructs the extension determine if the visitor is an instance of a custom custom extension visitor, and if so, visit it using that method. If the visitor is is not an instance of the customcustom extension visitor, this method MUST call visitor.visit(binding).

Due to issues with generics, the type parameters of this method do not not relate to the type ofof the provider. In practice, the 'B' type will always always be a supertype of 'T'.

Class ProvidesMethodBinding

An {@literal @}Provides binding or binding produced by a a ModuleAnnotatedMethodScanner. @since 4.0 @author sameb@google.com (Sam Berlin)
Class ProvidesMethodBinding, Annotation getAnnotation()

Returns the annotation that caused this binding to be created. For {@code @Provides} methods, this is an instance of the {@code @Provides} annotation. For bindings from from ModuleAnnotatedMethodScanner, this is the annotation that caused the scanner to produce produce thethe binding.
Class ProvidesMethodTargetVisitor

A visitor for the {@literal @}Provides bindings.

If your com.google.inject.spi.BindingTargetVisitor implements this interface, bindingsbindings created by using using {@code @Provides} will be visited through this interface. @since 4.0 @author sameb@google.com (Sam Berlin)

Class ProvisionListener

Listens for provisioning of objects. Useful for gathering timing information information about provisioning, post-provision initialization, and more. @author sameb@google.com (Sam Berlin) @since 4.0
Class ProvisionListener.ProvisionInvocation, Binding<T> getBinding()

Returns the Binding this is provisioning.

You must not call Provider.get() on the provider returned by by Binding.getProvider, otherwise you will get confusing error messages.

Class ProvisionListener.ProvisionInvocation, List<DependencyAndSource> getDependencyChain()

Returns the dependency chain that led to this object being provisioned. @deprecated This method is planned for removal in Guice 4.4. Some use cases can be replaced by inferring the current chain via ThreadLocals in the listener, other use cases can use the static dependency graph. For example, 
{@code
   bindListener(Matchers.any(), new MyListener());
   ...

   private static final class MyListener implements ProvisionListener {
     private final ThreadLocal>> bindingStack =
         new ThreadLocal>>() {
           {@literal @}Override protected ArrayDeque> initialValue() {
             return new ArrayDeque<();
           }
         };
     {@literal @}Override public  void onProvision(ProvisionInvocation invocation) {
       bindingStack.get().push(invocation.getBinding());
       try {
         invocation.provision();
       } finally {
         bindingStack.get().pop();
       }
       // Inspect the binding stack...
     }
   }

 }

 In this example the bindingStack thread local will contain a data structure that is very
 similar to the data returned by this list.  The main differences are that linked keys are
 not in the stack, but such edges do exist in the static dependency graph (inspectable via
 HasDependencies.getDependencies()), so you could infer some of the missing edges..
Class ProvisionListener, void onProvision(ProvisionInvocation<T>)

Invoked by Guice when an object requires provisioning. Provisioning occurs occurs when Guice locateslocates and injects the dependencies for a binding. For types types bound to a Provider, provisioningprovisioning encapsulates the Provider.get method. For toInstance or constant bindings, provisioning encapsulates provisioning encapsulates the injecting of {@literal @}{@code Inject}ed fields or methods. For other types, provisioning encapsulates the construction of the the object. If a type is bound within a Scope, provisioning depends on on the scope. Types bound in Singleton scope will only bebe provisioned once. Types bound in no scope will be provisioned every time they are injected. Other scopes define their own behavior for provisioning.

To perform the provision, call ProvisionInvocation.provision(). If you do notnot explicitly call provision, it will be automatically done after after this method returns. It is anan error to call provision more than once.

Class ScopeBinding

Registration of a scope annotation with the scope that implements it. Instances are created explicitly in a module using bindScope() statements: 
     Scope recordScope = new RecordScope();
     bindScope(RecordScoped.class, new RecordScope());
@author jessewilson@google.com (Jesse Wilson) @since 2.0
Class StaticInjectionRequest

A request to inject the static fields and methods of a type. Requests are created created explicitly in aa module using requestStaticInjection() statements: 
     requestStaticInjection(MyLegacyService.class);
@author jessewilson@google.com (Jesse Wilson) @since 2.0
Class StaticInjectionRequest, Set<InjectionPoint> getInjectionPoints()

Returns the static methods and fields of {@code type} that will be injected to fulfill this request. @return a possibly empty set of injection points. The set has a specified iteration order. All fields are returned and then all methods. Within the fields, supertype fields are returned before subtype fields. Similarly, supertype methods are returned before subtype methods. @throws ConfigurationException if there is a malformed injection point on {@code type}, such as a field with multiple binding annotations. The exception's partial value is a {@code Set} of of the valid injection points.
Class Toolable

Instructs an Injector running in Stage.TOOL that a method should be injected. This is typically useful for for extensions to Guice that perform additional validation in an injected method or field. This only applies to objects that are already constructed when bindingswhen bindings are created (ie., something bound using toProvider, toInstance, or requestInjection. @author sberlin@gmail.com (Sam Berlin) @since 3.0
Class TypeConverterBinding

Registration of type converters for matching target types. Instances are created created explicitly in aa module using convertToTypes() statements: 
     convertToTypes(Matchers.only(TypeLiteral.get(DateTime.class)), new DateTimeConverter());
@author jessewilson@google.com (Jesse Wilson) @since 2.0
Class TypeEncounter

Context of an injectable type encounter. Enables reporting errors, registering injection listeners and binding method interceptors for injectable type {@code I}. It is an error to use anuse an encounter after the hear() method has returned. @param the injectable type encountered @since 2.0
Class TypeEncounter, void addError(String, Object[])

Records an error message for type {@code I} which will be presented to the user at a later time. Unlike throwing an exception, this enable us to continue configuring the Injector and discover more errors. Uses String.format(String, Object[]) to insert the arguments intoarguments into the message.
Class TypeEncounter, void bindInterceptor(Matcher<Method>, MethodInterceptor[])

Binds method interceptor[s] to methods matched in type {@code I} and its supertypes. A methodA method is eligible for interception if: @param methodMatcher matches methods the interceptor should apply to. For For example: {@codecode annotatedWith(Transactional.class)}. @param interceptors to bind
Class TypeEncounter, MembersInjector<T> getMembersInjector(Class<T>)

Returns the members injector used to inject dependencies into methods and fields on instances of the given type {@code T}. The returned members injector will not be valid until the main injector has been created. The members injector will throw an {@code IllegalStateException} ifif you try to use it beforehand. @param type type to get members injector for
Class TypeEncounter, MembersInjector<T> getMembersInjector(TypeLiteral<T>)

Returns the members injector used to inject dependencies into methods and fields on instances of the given type {@code T}. The returned members injector will not be valid until the main injector has been created. The members injector will throw an {@code IllegalStateException} ifif you try to use it beforehand. @param typeLiteral type to get members injector for
Class TypeListener

Listens for Guice to encounter injectable types. If a given type has its constructor injected in one situation but only its methods and fields injected in another, Guice will notify this listener once.

Useful for extra type checking, TypeEncounter#register(InjectionListener) registering injection listeners, and TypeEncounter#bindInterceptor( com.google.inject.matcher.Matcher, org.aopalliance.intercept.MethodInterceptor[]) binding methodmethod interceptors. @since 2.0

Class TypeListener, void hear(TypeLiteral<I>, TypeEncounter<I>)

Invoked when Guice encounters a new type eligible for constructor or members injection. CalledCalled during injector creation (or afterwards if Guice encounters a type at run time and and creates aa JIT binding). @param type encountered by Guice @param encounter context of this encounter, enables reporting errors, registering injection listeners and binding method interceptors for {@code type}. @param the injectable type