com.surelogic

Annotation Type Singleton

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Singleton

The class to which this annotation is applied is a singleton, meaning it has only one instance and provides a global point of access to that instance. That is, the class is a Java implementation of the Singleton pattern described by Gamma, Helm, Johnson, and Vlissides in Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley 1995). Several Java implementation patterns are supported. The supported singleton implementation patterns are presented by Joshua Bloch in Effective Java (Second Edition) (Addison-Wesley 2008) Item 1.

The recommended implementation approach, by Bloch, is to use the enum singleton implementation pattern, this implies

• the enum has only a single element that is recommended, but not mandated, to be called INSTANCE.

This implementation approach is concise, handles serialization properly, and will always have one instance—even when serialization or reflection are used in an attempt to create multiple instances.

Three implementation approaches are allowed if the singleton is implemented as a class. All require that the class is declared final and that the constructor is private. Further, if the singleton class is serializable then it must

• implement Serializable,
• declare all instance fields transient, and
• provide a readResolve method that returns the singleton instance (typically referenced in the static field INSTANCE).

The first implementation pattern uses a public static final field to hold the singleton reference. The recommended, but not mandated, field name is INSTANCE.

The second implementation pattern uses a private static final field to hold the singleton reference and a public static method to obtain the instance. The recommended, but not mandated, field name is INSTANCE. The recommended, but not mandated, method name is getInstance.

The third implementation pattern uses the lazy initialization holder class idiom described by Joshua Bloch in Effective Java (Second Edition) (Addison-Wesley 2008) Item 71. In this approach the singleton contains a private static class that holds the reference to the singleton object in a static final field. The recommended, but not mandated, nested class name is LazyInitilizationHolder. The singleton contains a public static method to obtain the instance. The recommended, but not mandated, field name is INSTANCE. The recommended, but not mandated, method name is getInstance.

Access to the singleton object via INSTANCE or getInstance is multi-thread safe. Note that this does not mean that the singleton's state is thread safe—it may be or it may not be—just that access to the reference is safely shared if clients use INSTANCE or getInstance to obtain the reference to the singleton.

It is a modeling error to apply this annotation to an interface.

Semantics:

The class to which this annotation is applied has one and only one instance and provides a global point of access to that instance. Further, the class is not allowed to be subclassed. The class may have mutable state.

Examples:

An example of the enum singleton implementation pattern is shown in the code below.

 @Singleton
 public enum Elvis {
        INSTANCE;
 
        private int age;
 
        public int getAge() {
                return age;
        }
 
        public void setAge(int value) {
                age = value;
        }
 }
 

An example of the public static field singleton implementation pattern is shown in the code below.

 @Singleton
 public final class Elvis {
        public static final Elvis INSTANCE = new Elvis();
 
        private Elvis() {
                // only one
        }
 
        private int age;
 
        public int getAge() {
                return age;
        }
 
        public void setAge(int value) {
                age = value;
        }
 }
 

An example of the private static field singleton implementation pattern is shown in the code below.

 @Singleton
 public final class Elvis {
        private static final Elvis INSTANCE = new Elvis();
 
        private Elvis() {
                // only one
        }
 
        public static Elvis getInstance() {
                return INSTANCE;
        }
 
        private int age;
 
        public int getAge() {
                return age;
        }
 
        public void setAge(int value) {
                age = value;
        }
 }
 

An example of a singleton that is serializable. This approach is supported, but not recommended, use the enum implementation pattern instead.

 @Singleton
 public final class Elvis implements Serializable {
        private static final long serialVersionUID = -5264712062432607599L;
 
        private Object readResolve() {
                return INSTANCE;
        }
 
        private static final Elvis INSTANCE = new Elvis();
 
        private Elvis() {
                // singleton
        }
 
        public static Elvis getInstance() {
                return INSTANCE;
        }
 
        private transient int age;
 
        public int getAge() {
                return age;
        }
 
        public void setAge(int value) {
                age = value;
        }
 }
 

An example of the lazy initialization singleton implementation pattern is shown in the code below.

 @Singleton
 public final class Elvis {
 
        private static class LazyInitilizationHolder {
                private static final Elvis INSTANCE = new Elvis();
        }
 
        private Elvis() {
                // only one
        }
 
        public static Elvis getInstance() {
                return LazyInitilizationHolder.INSTANCE;
        }
 
        private int age;
 
        public int getAge() {
                return age;
        }
 
        public void setAge(int value) {
                age = value;
        }
 }
 

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag.

 /**
  * @annotate Singleton
  */
 public final class Elvis {
   ...
 }