Injectable Singleton

From APIDesign

Singletons are sometimes dishonest as a design anti-pattern. Right, one may use them improperly, but with guidance of proper methodology there is nothing wrong on singletons. This page provides step by step cook book for usage of so called Injected Singletons.

What this is not

We are going to introduce an enhanced version of the singleton pattern that supports testability, provides smooth Convention over Configuration and Component Injection. It can be seen as nice alternative companion to application context used by dependency injection.

However when talking about singleton pattern, don't imagine Java's SecurityManager or URLStreamHandlerFactory. Those are not Injectable Singletons, they require non-trivial amount of initialization code and basically let your application knowledge leak out through out the system.

Defining the Singleton

Imagine you want to create a singleton service to display questions to the user. This would be your API:

does not exists: singletons.injectable.api

Slightly surprising thing is that the class is abstract (e.g. it contains no implementation) and to allow extensibility it provides protected constructor. This is not what traditional singletons usually do, but remember this is an Injectable Singleton!

As the important motto of Injectable Singletons is Convention over Configuration each such singleton needs to define default (even dummy) implementation. Let's do it like this:

does not exists: singletons.injectable.dummyimpl

In this case, the implementation of the yesOrNo method is really trivial and not very useful, but often there are cases when the default behavior can be made acceptable for many purposes.

Now the time as come to write proper initialization code (that will support extensibility). We can do it either in Java6 standard way via ServiceLoader:

does not exists: singletons.injectable.serviceloader

Or using small Lookup library (we'll see later what benefit it provides):

does not exists: singletons.injectable.lookup

And that is all. Our first, Injectable Singleton is ready for being used.

Usage

To use a singleton, it is enough to import its API class and call its methods. Because singletons are inherently initialized - e.g. as soon as one calls their static getter, one gets initialized instance - there is no need for any special configuration in the client code. Just:

does not exists: singletons.injectable.usage

This makes the whole use as simple as possible by following half of the Convention over Configuration motto: If you are OK with default implementation, just use it. As soon as you link with the API class, you can be sure that you'll get reasonable implementation. No other configuration is needed. This is the output of such sample execution:

$ java -jar DisplayerMain.jar -cp Displayer.jar
Saying no to 'Do you like singletons?'
Visit http://singletons.apidesign.org to change your mind!

Configure

Of course, using the dummy implementation is not always optimal. As our systems get more and more assembled at deploy time there especially needs to be a way to support easy configuration during application deployment. This is inherently supported due to adherence to Java Standard Extension Mechanism. Any time later, in any additional project that produces completely independent JAR file one can compile following piece of code:

does not exists: singletons.injectable.implement

The JAR containing this class (and the generated META-INF/services/ entry, as generated by processing @ServiceProvider annotation via compile time AnnotationProcessor or alternatively created manually) can be put onto the application classpath. As soon as you do

$ java -jar DisplayerMain.jar -cp Displayer.jar:DefaultDisplayerImpl.jar

your system will get properly configured and will use the injected enhanced singleton:

Don't waste time writing configuration files! All you need to do to configure Injectable Singletons is to include correct JARs on application classpath. Follow the second part of the Convention over Configuration motto. Let application assemblers dissatisfied with default, drop-in their implementations to classpath!

Testability

TBD. Use MockServices

• mention testing limitations due to levels of Co-existence and solutions

Injectable Meta-Singleton

• Lookup is meta!