Added code comments.

service-layer/src/main/java/com/iluwatar/app/App.java

@@ -1,5 +1,7 @@
 package com.iluwatar.app;
 
+import java.util.List;
+
 import com.iluwatar.magic.MagicService;
 import com.iluwatar.magic.MagicServiceImpl;
 import com.iluwatar.spell.Spell;
@@ -14,18 +16,34 @@ import com.iluwatar.wizard.WizardDaoImpl;
 
 
 /**
+ * Service layer defines an application's boundary with a layer of services that establishes 
+ * a set of available operations and coordinates the application's response in each operation.
  * 
+ * Enterprise applications typically require different kinds of interfaces to the data 
+ * they store and the logic they implement: data loaders, user interfaces, integration gateways, 
+ * and others. Despite their different purposes, these interfaces often need common interactions 
+ * with the application to access and manipulate its data and invoke its business logic. The 
+ * interactions may be complex, involving transactions across multiple resources and the 
+ * coordination of several responses to an action. Encoding the logic of the interactions 
+ * separately in each interface causes a lot of duplication.
  * 
+ * The example application demonstrates interactions between a client (App) and a service 
+ * (MagicService). The service is implemented with 3-layer architecture (entity, dao, service).
+ * For persistence the example uses in-memory H2 database which is populated on each application
+ * startup.
  *
  */
 public class App {
 	
     public static void main( String[] args ) {   
+    	// populate the in-memory database
     	initData();
+    	// query the data using the service
     	queryData();
     }
     
     public static void initData() {
+    	// spells
     	Spell spell1 = new Spell("Ice dart");
     	Spell spell2 = new Spell("Invisibility");
     	Spell spell3 = new Spell("Stun bolt");
@@ -62,6 +80,7 @@ public class App {
     	spellDao.persist(spell16);
     	spellDao.persist(spell17);
     	
+    	// spellbooks
     	SpellbookDao spellbookDao = new SpellbookDaoImpl();
     	Spellbook spellbook1 = new Spellbook("Book of Orgymon");
     	spellbookDao.persist(spellbook1);
@@ -102,6 +121,7 @@ public class App {
     	spellbook7.addSpell(spell17);
     	spellbookDao.merge(spellbook7);
     	
+    	// wizards
     	WizardDao wizardDao = new WizardDaoImpl();
     	Wizard wizard1 = new Wizard("Aderlard Boud");
     	wizardDao.persist(wizard1);
@@ -138,5 +158,15 @@ public class App {
     	for (Spell s: service.findAllSpells()) {
     		System.out.println(s.getName());
     	}
+    	System.out.println("Find wizards with spellbook 'Book of Idores'");
+    	List<Wizard> wizardsWithSpellbook = service.findWizardsWithSpellbook("Book of Idores");
+    	for (Wizard w: wizardsWithSpellbook) {
+    		System.out.println(String.format("%s has 'Book of Idores'", w.getName()));
+    	}
+    	System.out.println("Find wizards with spell 'Fireball'");
+    	List<Wizard> wizardsWithSpell = service.findWizardsWithSpell("Fireball");
+    	for (Wizard w: wizardsWithSpell) {
+    		System.out.println(String.format("%s has 'Fireball'", w.getName()));
+    	}
     }
 }

service-layer/src/main/java/com/iluwatar/common/BaseEntity.java

@@ -5,6 +5,11 @@ import javax.persistence.InheritanceType;
 import javax.persistence.MappedSuperclass;
 import javax.persistence.Version;
 
+/**
+ * 
+ * Base class for entities.
+ *
+ */
 @MappedSuperclass
 @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS)
 public class BaseEntity {

service-layer/src/main/java/com/iluwatar/common/Dao.java

@@ -2,6 +2,13 @@ package com.iluwatar.common;
 
 import java.util.List;
 
+/**
+ * 
+ * Dao interface.
+ *
+ * @param <E>
+ * 
+ */
 public interface Dao<E extends BaseEntity> {
 
 	E find(Long id);

service-layer/src/main/java/com/iluwatar/common/DaoBaseImpl.java

@@ -10,6 +10,13 @@ import org.hibernate.criterion.Restrictions;
 
 import com.iluwatar.hibernate.HibernateUtil;
 
+/**
+ * 
+ * Base class for Dao implementations.
+ *
+ * @param <E>
+ * 
+ */
 public abstract class DaoBaseImpl<E extends BaseEntity> implements Dao<E> {
 	
 	@SuppressWarnings("unchecked")

service-layer/src/main/java/com/iluwatar/hibernate/HibernateUtil.java

@@ -7,6 +7,11 @@ import com.iluwatar.spell.Spell;
 import com.iluwatar.spellbook.Spellbook;
 import com.iluwatar.wizard.Wizard;
 
+/**
+ * 
+ * Produces the Hibernate SessionFactory.
+ *
+ */
 public class HibernateUtil {
 
 	private static final SessionFactory sessionFactory;

service-layer/src/main/java/com/iluwatar/magic/MagicService.java

@@ -7,6 +7,11 @@ import com.iluwatar.spellbook.Spellbook;
 import com.iluwatar.wizard.Wizard;
 
 
+/**
+ * 
+ * Service interface.
+ *
+ */
 public interface MagicService {
 
 	List<Wizard> findAllWizards();
@@ -14,5 +19,8 @@ public interface MagicService {
 	List<Spellbook> findAllSpellbooks();
 	
 	List<Spell> findAllSpells();
-	
+
+	List<Wizard> findWizardsWithSpellbook(String name);
+
+	List<Wizard> findWizardsWithSpell(String name);
 }

service-layer/src/main/java/com/iluwatar/magic/MagicServiceImpl.java

@@ -1,5 +1,6 @@
 package com.iluwatar.magic;
 
+import java.util.ArrayList;
 import java.util.List;
 
 import com.iluwatar.spell.Spell;
@@ -9,6 +10,11 @@ import com.iluwatar.spellbook.SpellbookDao;
 import com.iluwatar.wizard.Wizard;
 import com.iluwatar.wizard.WizardDao;
 
+/**
+ * 
+ * Service implementation.
+ *
+ */
 public class MagicServiceImpl implements MagicService {
 	
 	private WizardDao wizardDao;
@@ -35,4 +41,17 @@ public class MagicServiceImpl implements MagicService {
 	public List<Spell> findAllSpells() {
 		return spellDao.findAll();
 	}
+
+	@Override
+	public List<Wizard> findWizardsWithSpellbook(String name) {
+		Spellbook spellbook = spellbookDao.findByName(name);
+		return new ArrayList<Wizard>(spellbook.getWizards());
+	}
+
+	@Override
+	public List<Wizard> findWizardsWithSpell(String name) {
+		Spell spell = spellDao.findByName(name);
+		Spellbook spellbook = spell.getSpellbook();
+		return new ArrayList<Wizard>(spellbook.getWizards());
+	}
 }

service-layer/src/main/java/com/iluwatar/spell/Spell.java

@@ -11,6 +11,11 @@ import javax.persistence.Table;
 import com.iluwatar.common.BaseEntity;
 import com.iluwatar.spellbook.Spellbook;
 
+/**
+ * 
+ * Spell entity.
+ *
+ */
 @Entity
 @Table(name="SPELL")
 public class Spell extends BaseEntity {

service-layer/src/main/java/com/iluwatar/spell/SpellDao.java

@@ -2,6 +2,11 @@ package com.iluwatar.spell;
 
 import com.iluwatar.common.Dao;
 
+/**
+ * 
+ * SpellDao interface.
+ *
+ */
 public interface SpellDao extends Dao<Spell> {
 	
 	Spell findByName(String name);

service-layer/src/main/java/com/iluwatar/spell/SpellDaoImpl.java

@@ -7,6 +7,11 @@ import org.hibernate.criterion.Expression;
 
 import com.iluwatar.common.DaoBaseImpl;
 
+/**
+ * 
+ * SpellDao implementation.
+ *
+ */
 public class SpellDaoImpl extends DaoBaseImpl<Spell> implements SpellDao {
 
 	@Override
@@ -19,6 +24,7 @@ public class SpellDaoImpl extends DaoBaseImpl<Spell> implements SpellDao {
 			Criteria criteria = session.createCriteria(persistentClass);
 			criteria.add(Expression.eq("name", name));
 			result = (Spell) criteria.uniqueResult();
+			result.getSpellbook().getWizards().size();
 			tx.commit();
 		}
 		catch (Exception e) {

service-layer/src/main/java/com/iluwatar/spellbook/Spellbook.java

@@ -16,6 +16,11 @@ import com.iluwatar.common.BaseEntity;
 import com.iluwatar.spell.Spell;
 import com.iluwatar.wizard.Wizard;
 
+/**
+ * 
+ * Spellbook entity.
+ *
+ */
 @Entity
 @Table(name="SPELLBOOK")
 public class Spellbook extends BaseEntity {

service-layer/src/main/java/com/iluwatar/spellbook/SpellbookDao.java

@@ -2,6 +2,11 @@ package com.iluwatar.spellbook;
 
 import com.iluwatar.common.Dao;
 
+/**
+ * 
+ * SpellbookDao interface.
+ *
+ */
 public interface SpellbookDao extends Dao<Spellbook> {
 	
 	Spellbook findByName(String name);

service-layer/src/main/java/com/iluwatar/spellbook/SpellbookDaoImpl.java

@@ -7,6 +7,11 @@ import org.hibernate.criterion.Expression;
 
 import com.iluwatar.common.DaoBaseImpl;
 
+/**
+ * 
+ * SpellbookDao implementation.
+ *
+ */
 public class SpellbookDaoImpl extends DaoBaseImpl<Spellbook> implements SpellbookDao {
 
 	@Override

service-layer/src/main/java/com/iluwatar/wizard/Wizard.java

@@ -14,6 +14,11 @@ import javax.persistence.Table;
 import com.iluwatar.common.BaseEntity;
 import com.iluwatar.spellbook.Spellbook;
 
+/**
+ * 
+ * Wizard entity.
+ *
+ */
 @Entity
 @Table(name="WIZARD")
 public class Wizard extends BaseEntity {

service-layer/src/main/java/com/iluwatar/wizard/WizardDao.java

@@ -2,6 +2,11 @@ package com.iluwatar.wizard;
 
 import com.iluwatar.common.Dao;
 
+/**
+ * 
+ * WizardDao interface.
+ *
+ */
 public interface WizardDao extends Dao<Wizard> {
 	
 	Wizard findByName(String name);

service-layer/src/main/java/com/iluwatar/wizard/WizardDaoImpl.java

@@ -6,7 +6,13 @@ import org.hibernate.Transaction;
 import org.hibernate.criterion.Expression;
 
 import com.iluwatar.common.DaoBaseImpl;
+import com.iluwatar.spellbook.Spellbook;
 
+/**
+ * 
+ * WizardDao implementation.
+ *
+ */
 public class WizardDaoImpl extends DaoBaseImpl<Wizard> implements WizardDao {
 
 	@Override
@@ -19,7 +25,9 @@ public class WizardDaoImpl extends DaoBaseImpl<Wizard> implements WizardDao {
 			Criteria criteria = session.createCriteria(persistentClass);
 			criteria.add(Expression.eq("name", name));
 			result = (Wizard) criteria.uniqueResult();
-			result.getSpellbooks().size();
+			for (Spellbook s: result.getSpellbooks()) {
+				s.getSpells().size();
+			}
 			tx.commit();
 		}
 		catch (Exception e) {