xapi.inject

Class X_Inject

java.lang.Object

xapi.inject.X_Inject

@KeepMethod
public class X_Inject
extends Object

A static accessor class for in an instance of Injector.

Classes marked with SingletonDefault or SingletonOverride are usable by X_Inject. Once a class has been marked as a service provider for a given interface or class, it can be used in cross-platform code as follows:

static interface MyService{}

@SingletonDefault(implFor=MyService.class)

static class MyServiceImpl implements MyService{}

MyService service = X_Inject.singleton(MyService.class);//returns MyServiceImpl

All actual injection occurs in implementations of Injector.

The pure-java solution uses JavaInjector, which is based on the jre6 ServiceLoader, with some tweaks to match the gwt injector behavior. Files with the name equal to the interface or class being injected are written to META-INF/singletons for services to be instantiated only once per runtime. META-INF/instances is for objects that should be new copies for every request. A third form as META-INF/threadlocal may be provided for thread-local or process-local services, to help separated code share state without explicit reference passing. This option will be considered if the concurrency model is able to offer lifecycle events to ensure the gc of process-local singletons.

The gwt solution uses a generated extension of JsInjector using AsyncProxy. See generators.GwtDevGenerator and its subclass AbstractInjectionGenerator in the xapi-gwt-inject module.

Unlike ServiceLoader, which presents an iterable of available services, X_Inject currently only returns the highest priority (top of the list) service, and it only returns lazily-loaded singletons (which work with code splitting).

Note, all static service accessors in XApi are prefixed with X_, to make exposed services easier to discover in autocomplete.

Author:

James X. Nelson (james@wetheinter.net, @james)

Method Summary

Modifier and Type	Method and Description
static void	initialize(Object o)
static <T> T	instance(Class<? super T> cls)
static <T> T	singleton(Class<? super T> cls) Returns an injected singleton service implementation object.
static <T> void	singletonAsync(Class<? super T> cls, Class<? extends ReceivesValue<T>> callback)
static <T> void	singletonAsync(Class<? super T> cls, ReceivesValue<T> callback) Asynchronously loads an injected singleton service implementation object.
static <T> javax.inject.Provider<T>	singletonLazy(Class<? super T> cls) This is a magic method, like gwt.create.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

initialize

public static void initialize(Object o)

instance

@KeepMethod
 @MagicMethod(doNotVisit=true)
public static <T> T instance(Class<? super T> cls)

singleton

@KeepMethod
 @MagicMethod(doNotVisit=true)
public static <T> T singleton(Class<? super T> cls)

Returns an injected singleton service implementation object. WARNING: When running in compiled gwt mode with code splitting, if you use the asynchronous provider method singletonAsync(Class, ReceivesValue), then the synchronous providers, singleton(Class) and singletonLazy(Class) will return null until the code split containing the service is loaded. TODO: use AsyncProxy from If you have ANY doubt about whether a service is already loaded or not, please prefer the async provider method {@link #singletonAsync(Class, ReceivesValue)

Parameters:

cls - - The service interface / base class to inject.

Returns:

- An instance of the requested class, based on DI annotations.

There must be at least one class on your classpath which is annotated with SingletonDefault or SingletonOverride, and which implements or overrides the service being provided.

You are recommended to use only interfaces in service definitions, but you are free to use classes if you wish.

It is valid to annotate a class as it's own default implementation.

singletonAsync

@KeepMethod
 @MagicMethod(doNotVisit=true)
public static <T> void singletonAsync(Class<? super T> cls,
                                                                                 Class<? extends ReceivesValue<T>> callback)

singletonAsync

@KeepMethod
 @MagicMethod(doNotVisit=true)
public static <T> void singletonAsync(Class<? super T> cls,
                                                                                 ReceivesValue<T> callback)

Asynchronously loads an injected singleton service implementation object. This method uses gwt code splitting to put each service into it's own island loader. It will create a split for every service, but with the closure compiler and CodeSplitter2, the compiler will do a very good job of modularizing and optimizing split points.

WARNING: If you use async loading for a service provider in one place, and then use synchronous methods singleton(Class) or singletonLazy(Class), the synchronous methods will return null in gwt production mode until after the split point is loaded. If you have any doubts about whether a given service is already loaded, always prefer this asynchronous provider method instead of the sync ones.

In compiled gwt, this is treated as a magic method which generators provider classes. In gwt dev mode, it defers to a single class which provides all injected object. In pure java mode, it relies on java.util.ServiceLoader. Running either gwt dev or a full gwt compile will generate META-INF/singletons for you.

Parameters:

cls - - The service interface / base class to inject.

callback - - The ReceivesValue to notify when the object is loaded.

There must be at least one class on your classpath which is annotated with SingletonDefault or SingletonOverride, and which implements or overrides the service being provided.

You are recommended to use only interfaces in service definitions, but you are free to use classes if you wish.

It is valid to annotate a class as it's own default implementation.

singletonLazy

@KeepMethod
 @MagicMethod(doNotVisit=true)
public static <T> javax.inject.Provider<T> singletonLazy(Class<? super T> cls)

This is a magic method, like gwt.create. It is replaced in UnifyAst with references to generated classes. In pure java implementations, it defers to either a generated provider class for gwt-dev, and to ServiceLoader.load() for pure java implementations.

Parameters:

cls - - The interface or base class to be injected

Returns:

- A provider which will return the loaded injected class. WARNING: In gwt production mode, if you use code splitting to move a provider into it's own async splitpoint, any other split points which use synchronous access will return null until loaded. If you have any doubts about the timing and load sequence, always prefer the singletonAsync(Class, ReceivesValue) method.