Added source code comments.

iluwatar · iluwatar · commit 0c0d84c22087 · 2015-05-25T19:13:50.000+03:00
diff --git a/dependency-injection/src/main/java/com/iluwatar/AdvancedWizard.java b/dependency-injection/src/main/java/com/iluwatar/AdvancedWizard.java
@@ -1,5 +1,12 @@
 package com.iluwatar;
 
+/**
+ * 
+ * AdvancedWizard implements inversion of control.
+ * It depends on abstraction that can be injected through
+ * its constructor.
+ *
+ */
 public class AdvancedWizard implements Wizard {
 	
 	private Tobacco tobacco;
diff --git a/dependency-injection/src/main/java/com/iluwatar/App.java b/dependency-injection/src/main/java/com/iluwatar/App.java
@@ -3,6 +3,27 @@
 import com.google.inject.Guice;
 import com.google.inject.Injector;
 
+/**
+ * 
+ * Dependency Injection pattern deals with how objects handle their dependencies. The pattern 
+ * implements so called inversion of control principle. Inversion of control has two specific rules:
+ *  - High-level modules should not depend on low-level modules. Both should depend on abstractions.
+ *  - Abstractions should not depend on details. Details should depend on abstractions.
+ *  
+ *  In this example we show you three different wizards. The first one (SimpleWizard) is a naive 
+ *  implementation violating the inversion of control principle. It depends directly on a concrete
+ *  implementation which cannot be changed.
+ *  
+ *  The second wizard (AdvancedWizard) is more flexible. It does not depend on any concrete implementation 
+ *  but abstraction. It utilizes Dependency Injection pattern allowing its Tobacco dependency to be
+ *  injected through its constructor. This way, handling the dependency is no longer the wizard's
+ *  responsibility. It is resolved outside the wizard class.
+ *  
+ *  The third example takes the pattern a step further. It uses Guice framework for Dependency Injection.
+ *  TobaccoModule binds a concrete implementation to abstraction. Injector is then used to create
+ *  GuiceWizard object with correct dependencies.
+ *
+ */
 public class App {
 	
     public static void main( String[] args ) {
diff --git a/dependency-injection/src/main/java/com/iluwatar/GuiceWizard.java b/dependency-injection/src/main/java/com/iluwatar/GuiceWizard.java
@@ -2,6 +2,13 @@
 
 import javax.inject.Inject;
 
+/**
+ * 
+ * GuiceWizard implements inversion of control.
+ * Its dependencies are injected through its constructor
+ * by Guice framework.
+ *
+ */
 public class GuiceWizard implements Wizard {
 	
 	private Tobacco tobacco;
diff --git a/dependency-injection/src/main/java/com/iluwatar/OldTobyTobacco.java b/dependency-injection/src/main/java/com/iluwatar/OldTobyTobacco.java
@@ -1,4 +1,9 @@
 package com.iluwatar;
 
+/**
+ * 
+ * OldTobyTobacco concrete Tobacco implementation
+ *
+ */
 public class OldTobyTobacco extends Tobacco {
 }
diff --git a/dependency-injection/src/main/java/com/iluwatar/RivendellTobacco.java b/dependency-injection/src/main/java/com/iluwatar/RivendellTobacco.java
@@ -1,4 +1,9 @@
 package com.iluwatar;
 
+/**
+ * 
+ * RivendellTobacco concrete Tobacco implementation
+ *
+ */
 public class RivendellTobacco extends Tobacco {
 }
diff --git a/dependency-injection/src/main/java/com/iluwatar/SecondBreakfastTobacco.java b/dependency-injection/src/main/java/com/iluwatar/SecondBreakfastTobacco.java
@@ -1,4 +1,9 @@
 package com.iluwatar;
 
+/**
+ * 
+ * SecondBreakfastTobacco concrete Tobacco implementation
+ *
+ */
 public class SecondBreakfastTobacco extends Tobacco {
 }
diff --git a/dependency-injection/src/main/java/com/iluwatar/SimpleWizard.java b/dependency-injection/src/main/java/com/iluwatar/SimpleWizard.java
@@ -1,5 +1,11 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Naive Wizard implementation violating the inversion of control principle.
+ * It should depend on abstraction instead.
+ *
+ */
 public class SimpleWizard implements Wizard {
 	
 	private OldTobyTobacco tobacco = new OldTobyTobacco();
diff --git a/dependency-injection/src/main/java/com/iluwatar/Tobacco.java b/dependency-injection/src/main/java/com/iluwatar/Tobacco.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Tobacco abstraction
+ *
+ */
 public abstract class Tobacco {
 	
 	public void smoke(Wizard wizard) {
diff --git a/dependency-injection/src/main/java/com/iluwatar/TobaccoModule.java b/dependency-injection/src/main/java/com/iluwatar/TobaccoModule.java
@@ -2,6 +2,11 @@
 
 import com.google.inject.AbstractModule;
 
+/**
+ * 
+ * Guice module for binding certain concrete Tobacco implementation.
+ *
+ */
 public class TobaccoModule extends AbstractModule {
 
 	@Override
diff --git a/dependency-injection/src/main/java/com/iluwatar/Wizard.java b/dependency-injection/src/main/java/com/iluwatar/Wizard.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Wizard interface
+ *
+ */
 public interface Wizard {
 	
 	void smoke();

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,9 @@`
`1`	`1`	`package com.iluwatar;`
`2`	`2`
	`3`	`+/**`
	`4`	`+ *`
	`5`	`+ * OldTobyTobacco concrete Tobacco implementation`
	`6`	`+ *`
	`7`	`+ */`
`3`	`8`	`public class OldTobyTobacco extends Tobacco {`
`4`	`9`	`}`