#107 JavaDoc for Singleton

singleton/src/main/java/com/iluwatar/singleton/App.java

@@ -1,51 +1,55 @@
-package com.iluwatar.singleton;
+package com.iluwatar.singleton;
-
+
-/**
+/**
- *
+ *
- * Singleton pattern ensures that the class (IvoryTower) can have only one
+ * Singleton pattern ensures that the class ({@link IvoryTower}) can have only one
- * existing instance per java classloader instance and provides global access to it. 
+ * existing instance per Java classloader instance and provides global access to it. 
- * 
+ * <p>
- * http://stackoverflow.com/questions/70689/what-is-an-efficient-way-to-implement-a-singleton-pattern-in-java
+ * http://stackoverflow.com/questions/70689/what-is-an-efficient-way-to-implement-a-singleton-pattern-in-java
- *
+ *<p>
- * The risk of this pattern is that bugs resulting from setting a singleton up in a distributed environment can 
+ * The risk of this pattern is that bugs resulting from setting a singleton up in a distributed environment can 
- * be tricky to debug, since it will work fine if you debug with a single classloader. Additionally, these
+ * be tricky to debug, since it will work fine if you debug with a single classloader. Additionally, these
- * problems can crop up a while after the implementation of a singleton, since they may start out synchronous and
+ * problems can crop up a while after the implementation of a singleton, since they may start out synchronous and
- * only become async with time, so you it may not be clear why you are seeing certain changes in behaviour.
+ * only become async with time, so you it may not be clear why you are seeing certain changes in behaviour.
- * 
+ * <p>
- * http://stackoverflow.com/questions/17721263/singleton-across-jvm-or-application-instance-or-tomcat-instance
+ * http://stackoverflow.com/questions/17721263/singleton-across-jvm-or-application-instance-or-tomcat-instance
- */
+ */
-public class App {
+public class App {
-
+
-	public static void main(String[] args) {
+	/**
-
+	 * Program entry point
-		// eagerly initialized singleton
+	 * @param args command line args
-		IvoryTower ivoryTower1 = IvoryTower.getInstance();
+	 */
-		IvoryTower ivoryTower2 = IvoryTower.getInstance();
+	public static void main(String[] args) {
-		System.out.println("ivoryTower1=" + ivoryTower1);
+
-		System.out.println("ivoryTower2=" + ivoryTower2);
+		// eagerly initialized singleton
-
+		IvoryTower ivoryTower1 = IvoryTower.getInstance();
-		// lazily initialized singleton
+		IvoryTower ivoryTower2 = IvoryTower.getInstance();
-		ThreadSafeLazyLoadedIvoryTower threadSafeIvoryTower1 = ThreadSafeLazyLoadedIvoryTower
+		System.out.println("ivoryTower1=" + ivoryTower1);
-				.getInstance();
+		System.out.println("ivoryTower2=" + ivoryTower2);
-		ThreadSafeLazyLoadedIvoryTower threadSafeIvoryTower2 = ThreadSafeLazyLoadedIvoryTower
+
-				.getInstance();
+		// lazily initialized singleton
-		System.out.println("threadSafeIvoryTower1=" + threadSafeIvoryTower1);
+		ThreadSafeLazyLoadedIvoryTower threadSafeIvoryTower1 = ThreadSafeLazyLoadedIvoryTower
-		System.out.println("threadSafeIvoryTower2=" + threadSafeIvoryTower2);
+				.getInstance();
-
+		ThreadSafeLazyLoadedIvoryTower threadSafeIvoryTower2 = ThreadSafeLazyLoadedIvoryTower
-		// enum singleton
+				.getInstance();
-		EnumIvoryTower enumIvoryTower1 = EnumIvoryTower.INSTANCE;
+		System.out.println("threadSafeIvoryTower1=" + threadSafeIvoryTower1);
-		EnumIvoryTower enumIvoryTower2 = EnumIvoryTower.INSTANCE;
+		System.out.println("threadSafeIvoryTower2=" + threadSafeIvoryTower2);
-		System.out.println("enumIvoryTower1=" + enumIvoryTower1);
+
-		System.out.println("enumIvoryTower2=" + enumIvoryTower2);
+		// enum singleton
-		
+		EnumIvoryTower enumIvoryTower1 = EnumIvoryTower.INSTANCE;
-		InitializingOnDemandHolderIdiom demandHolderIdiom = InitializingOnDemandHolderIdiom.getInstance();
+		EnumIvoryTower enumIvoryTower2 = EnumIvoryTower.INSTANCE;
-		System.out.println(demandHolderIdiom);
+		System.out.println("enumIvoryTower1=" + enumIvoryTower1);
-		InitializingOnDemandHolderIdiom demandHolderIdiom2 = InitializingOnDemandHolderIdiom.getInstance();
+		System.out.println("enumIvoryTower2=" + enumIvoryTower2);
-		System.out.println(demandHolderIdiom2);
+		
-		
+		InitializingOnDemandHolderIdiom demandHolderIdiom = InitializingOnDemandHolderIdiom.getInstance();
-		ThreadSafeDoubleCheckLocking dcl1 = ThreadSafeDoubleCheckLocking.getInstance();
+		System.out.println(demandHolderIdiom);
-		System.out.println(dcl1);
+		InitializingOnDemandHolderIdiom demandHolderIdiom2 = InitializingOnDemandHolderIdiom.getInstance();
-		ThreadSafeDoubleCheckLocking dcl2 = ThreadSafeDoubleCheckLocking.getInstance();
+		System.out.println(demandHolderIdiom2);
-		System.out.println(dcl2);
+		
-	}
+		ThreadSafeDoubleCheckLocking dcl1 = ThreadSafeDoubleCheckLocking.getInstance();
-}
+		System.out.println(dcl1);
+		ThreadSafeDoubleCheckLocking dcl2 = ThreadSafeDoubleCheckLocking.getInstance();
+		System.out.println(dcl2);
+	}
+}

singleton/src/main/java/com/iluwatar/singleton/InitializingOnDemandHolderIdiom.java

@@ -4,12 +4,12 @@ import java.io.Serializable;
 
 /**
  * The Initialize-on-demand-holder idiom is a secure way of 
- * creating lazy initialize singleton Object in Java.
+ * creating lazy initialized singleton object in Java.
  * refer to "The CERT Oracle Secure Coding Standard for Java"
  * By Dhruv Mohindra, Robert C. Seacord p.378
- * 
+ * <p>
  * Singleton objects usually are heavy to create and sometimes need to serialize them.
- * This class also shows how to preserve singleton in Serialized version of singleton.
+ * This class also shows how to preserve singleton in serialized version of singleton.
  * 
  * @author mortezaadi@gmail.com
  *

singleton/src/main/java/com/iluwatar/singleton/ThreadSafeDoubleCheckLocking.java

@@ -2,10 +2,11 @@ package com.iluwatar.singleton;
 
 /**
  * Double check locking
- * 
+ * <p>
  * http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html
- * 
+ * <p>
  * Broken under Java 1.4.
+ * 
  * @author mortezaadi@gmail.com
  *
  */

singleton/src/test/java/com/iluwatar/singleton/AppTest.java

@@ -1,14 +1,19 @@
-package com.iluwatar.singleton;
+package com.iluwatar.singleton;
-
+
-import org.junit.Test;
+import org.junit.Test;
-
+
-import com.iluwatar.singleton.App;
+import com.iluwatar.singleton.App;
-
+
-public class AppTest {
+/**
-
+ * 
-	@Test
+ * Application test
-	public void test() {
+ *
-		String[] args = {};
+ */
-		App.main(args);
+public class AppTest {
-	}
+
-}
+	@Test
+	public void test() {
+		String[] args = {};
+		App.main(args);
+	}
+}

singleton/src/test/java/com/iluwatar/singleton/LazyLoadedSingletonThreadSafetyTest.java

@@ -5,9 +5,9 @@ import org.junit.Test;
 /**
  * 
  * This test case demonstrates thread safety issues of lazy loaded Singleton implementation.
- * 
+ * <p>
  * Out of the box you should see the test output something like the following:
- * 
+ * <p>
  * Thread=Thread-4 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@6fde356e
  * Thread=Thread-2 creating instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@6fde356e
  * Thread=Thread-0 creating instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@6fde356e
@@ -15,13 +15,17 @@ import org.junit.Test;
  * Thread=Thread-3 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@6fde356e
  * Thread=Thread-1 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@60f330b0
  * Thread=Thread-2 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@6fde356e
- * 
+ * <p>
  * By changing the method signature of LazyLoadedIvoryTower#getInstance from
+ * <p><blockquote><pre>
  * 	 public static LazyLoadedIvoryTower getInstance()
+ * </pre></blockquote><p>
  * into
+ * <p><blockquote><pre>
  *   public synchronized static LazyLoadedIvoryTower getInstance()
+ * </pre></blockquote><p>
  * you should see the test output change to something like the following:
- * 
+ * <p>
  * Thread=Thread-4 creating instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@3c688490
  * Thread=Thread-4 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@3c688490
  * Thread=Thread-0 got instance=com.iluwatar.singleton.LazyLoadedSingletonThreadSafetyTest$LazyLoadedIvoryTower@3c688490