From 058cb87b402fa3826c327ddd6c310e2341b623a4 Mon Sep 17 00:00:00 2001
From: Ilkka Seppala <iluwatar@gmail.com>
Date: Wed, 29 Apr 2015 22:15:36 +0300
Subject: [PATCH] Code comments.

---
 .../src/main/java/com/iluwatar/App.java       | 10 +++++++
 .../main/java/com/iluwatar/RainbowFish.java   |  5 ++++
 .../com/iluwatar/RainbowFishSerializer.java   | 26 +++++++++++++++++++
 .../main/java/com/iluwatar/RainbowFishV2.java |  5 ++++
 4 files changed, 46 insertions(+)

diff --git a/tolerant-reader/src/main/java/com/iluwatar/App.java b/tolerant-reader/src/main/java/com/iluwatar/App.java
index a2b293ed9..6b6f1e8e6 100644
--- a/tolerant-reader/src/main/java/com/iluwatar/App.java
+++ b/tolerant-reader/src/main/java/com/iluwatar/App.java
@@ -4,7 +4,17 @@ import java.io.IOException;
 
 /**
  * 
+ * Tolerant Reader is an integration pattern that helps creating robust communication
+ * systems. The idea is to be as tolerant as possible when reading data from another
+ * service. This way, when the communication schema changes, the readers must not break.
  * 
+ * In this example we use Java serialization to write representations of RainbowFish
+ * objects to file. RainbowFish is the initial version which we can easily read and
+ * write using RainbowFishSerializer methods. RainbowFish then evolves to RainbowFishV2
+ * and we again write it to file with a method designed to do just that. However, the reader
+ * client does not know about the new format and still reads with the method designed for
+ * V1 schema. Fortunately the reading method has been designed with the Tolerant Reader
+ * pattern and does not break even though RainbowFishV2 has new fields that are serialized.
  *
  */
 public class App {
diff --git a/tolerant-reader/src/main/java/com/iluwatar/RainbowFish.java b/tolerant-reader/src/main/java/com/iluwatar/RainbowFish.java
index 102e7049e..8ab2b378c 100644
--- a/tolerant-reader/src/main/java/com/iluwatar/RainbowFish.java
+++ b/tolerant-reader/src/main/java/com/iluwatar/RainbowFish.java
@@ -2,6 +2,11 @@ package com.iluwatar;
 
 import java.io.Serializable;
 
+/**
+ * 
+ * RainbowFish is the initial schema
+ *
+ */
 public class RainbowFish implements Serializable {
 
 	private static final long serialVersionUID = 1L;
diff --git a/tolerant-reader/src/main/java/com/iluwatar/RainbowFishSerializer.java b/tolerant-reader/src/main/java/com/iluwatar/RainbowFishSerializer.java
index 60ed816e9..f654a8e09 100644
--- a/tolerant-reader/src/main/java/com/iluwatar/RainbowFishSerializer.java
+++ b/tolerant-reader/src/main/java/com/iluwatar/RainbowFishSerializer.java
@@ -9,8 +9,21 @@ import java.io.ObjectOutputStream;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * 
+ * RainbowFishSerializer provides methods for reading and writing RainbowFish objects to file.
+ * Tolerant Reader pattern is implemented here by serializing maps instead of RainbowFish objects.
+ * This way the reader does not break even though new properties are added to the schema.
+ *
+ */
 public class RainbowFishSerializer {
 
+	/**
+	 * Write V1 RainbowFish to file
+	 * @param rainbowFish
+	 * @param filename
+	 * @throws IOException
+	 */
 	public static void writeV1(RainbowFish rainbowFish, String filename) throws IOException {
 		Map<String, String> map = new HashMap<>();
 		map.put("name", rainbowFish.getName());
@@ -24,6 +37,12 @@ public class RainbowFishSerializer {
 		fileOut.close();
 	}
 
+	/**
+	 * Write V2 RainbowFish to file
+	 * @param rainbowFish
+	 * @param filename
+	 * @throws IOException
+	 */
 	public static void writeV2(RainbowFishV2 rainbowFish, String filename) throws IOException {
 		Map<String, String> map = new HashMap<>();
 		map.put("name", rainbowFish.getName());
@@ -40,6 +59,13 @@ public class RainbowFishSerializer {
 		fileOut.close();
 	}
 	
+	/**
+	 * Read V1 RainbowFish from file
+	 * @param filename
+	 * @return
+	 * @throws IOException
+	 * @throws ClassNotFoundException
+	 */
 	public static RainbowFish readV1(String filename) throws IOException, ClassNotFoundException {
 		Map<String, String> map = null;
 		FileInputStream fileIn = new FileInputStream(filename);
diff --git a/tolerant-reader/src/main/java/com/iluwatar/RainbowFishV2.java b/tolerant-reader/src/main/java/com/iluwatar/RainbowFishV2.java
index 775c5c8c7..89564fea0 100644
--- a/tolerant-reader/src/main/java/com/iluwatar/RainbowFishV2.java
+++ b/tolerant-reader/src/main/java/com/iluwatar/RainbowFishV2.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * RainbowFishV2 is the evolved schema
+ *
+ */
 public class RainbowFishV2 extends RainbowFish {
 
 	private static final long serialVersionUID = 1L;