Guice Custom Scopes

Guice custom scopes are, for some reason badly explained in almost all web documentation that I was able to find.  All implementations cover extra Guice concepts or muddy the code with concurrency handling while not describing the main concept which is surprisingly simple once realised.

A scope is a condition for reusing injected objects, instead of creating a new one each time.  For example, if a network connection was being injected then the scope would be while the network connection was open, reuse the object.  When it is closed, open and inject a new one.

The implementation for this is to basically provide a factory object,  implementing the Scope interface.  This has one method:

Provider scope(Key<T> key, Provider<T> unscoped)

The Key object defines the injected type, the unscoped Provider can be used to create a new instance.  Typically the returned Provider implementation will  create the required object using the unscoped Provider and keep a reference to it while in scope.  When the object is requested again the stored object is returned if still in scope.  This example usage above is how I needed to use custom scopes but it is flexible enough to do all kinds of weird things.

Here is the Scope implementation.  It is a bit more complex than necessary because for this example I wanted to allow objects to be created out of scope.

	public class EnterableScope implements Scope
	{
	private HashMap<Key<?>, Object> values;
	public void enter()
	{
	values = new HashMap<Key<?>, Object>();
	}
	public void exit()
	{
	values = null;
	}
	@Override
	public <T> Provider<T> scope(final Key<T> key, final Provider<T> unscoped)
	{
	return new Provider<T>() {
	@Override
	@SuppressWarnings("unchecked")
	public T get()
	{
	// if values is null return null otherwise return the stored value of one exists
	Object object = values != null ? values.get(key) : null;
	if(object == null)
	{
	object = unscoped.get();
	// if we in scope, store it, otherwise always create a new one
	if(values != null)
	{
	values.put(key, object);
	}
	}
	return (T) object;
	}
	};
	}
	}

view raw EnterableScope.java hosted with ❤ by GitHub

Here is out annotation which we will use on classes that can be stored within the scope.

	@Target({ TYPE, METHOD }) @Retention(RUNTIME) @ScopeAnnotation
	public @interface BookScoped
	{
	}

view raw BookScoped.java hosted with ❤ by GitHub

The interface to inject:

	public interface Hero
	{
	}

view raw Hero.java hosted with ❤ by GitHub

The class that implements that interface to be injected.  Note that we have annotated this with our @BookScoped annotation.  The constructor will display new objects being created.

	@BookScoped
	public class Hobbit implements Hero
	{
	public Hobbit()
	{
	System.out.println("created " + toString());
	}
	}

view raw Hobbit.java hosted with ❤ by GitHub

Now our Guice module.  The scope annotation is bound to an EnterableScope instance which we'll keep a hold of.

	public class MiddleEarthModule extends AbstractModule
	{
	private final EnterableScope scope;
	public MiddleEarthModule()
	{
	scope = new EnterableScope();
	}
	@Override
	protected void configure()
	{
	bindScope(BookScoped.class, scope);
	bind(Hero.class).to(Hobbit.class);
	}
	public void enter()
	{
	scope.enter();
	}
	public void exit()
	{
	scope.exit();
	}
	}

view raw MiddleEarthModule.java hosted with ❤ by GitHub

Finally the main class to demo the scope.

	public class Main
	{
	public static void main(String[] args)
	{
	MiddleEarthModule module;
	module = new MiddleEarthModule();
	Injector injector;
	injector = Guice.createInjector(module);
	System.out.println("entering scope");
	module.enter();
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	System.out.println("exiting scope");
	module.exit();
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	injector.getInstance(Hero.class);
	}
	}

view raw Main.java hosted with ❤ by GitHub

When the main class is run it outputs the following to the command line:

entering scope
created customscopes.Hobbit@12a54f9
exiting scope
created customscopes.Hobbit@30e280
created customscopes.Hobbit@16672d6
created customscopes.Hobbit@fd54d6
created customscopes.Hobbit@1ccb029

When within scope the four calls to #getInstance only create one instance, when not in scope a new instance is created each time.  That's a whole lot of code although it is all fairly simple.  From a maintainability viewpoint I do see some issues with this, scopes are so arcane to anyone not experienced with Guice that it would be quite easy to misuse a scope which could cause all kinds of issues with retained state and possibly memory leaks.  All I can suggest is document everything and get this over to the team.