From 3f2e0e8eea2eea6cb173dc0d52d046f1363dde78 Mon Sep 17 00:00:00 2001
From: lucasward <lucasward@2e8e966d-6415-0410-94b9-dc4e65435d03>
Date: Fri, 21 Sep 2007 05:45:04 +0000
Subject: [PATCH] CLOSED - issue BATCH-136: restoreFromRestartData(Tasklet,
 RestartData) crashes if Properties are null
 http://opensource.atlassian.com/projects/spring/browse/BATCH-136

---
 .../batch/restart/GenericRestartData.java     |  6 ++--
 .../batch/restart/Restartable.java            | 33 ++++++++++++++++++-
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/infrastructure/src/main/java/org/springframework/batch/restart/GenericRestartData.java b/infrastructure/src/main/java/org/springframework/batch/restart/GenericRestartData.java
index 016f8956a..3a260cd6d 100644
--- a/infrastructure/src/main/java/org/springframework/batch/restart/GenericRestartData.java
+++ b/infrastructure/src/main/java/org/springframework/batch/restart/GenericRestartData.java
@@ -21,13 +21,13 @@ import java.util.Properties;
 public class GenericRestartData implements RestartData {
 
 	private Properties data;
-	
+
 	public GenericRestartData(Properties data){
 		this.data = data;
 	}
-	
+
 	public Properties getProperties(){
 		return data;
 	}
-	
+
 }
diff --git a/infrastructure/src/main/java/org/springframework/batch/restart/Restartable.java b/infrastructure/src/main/java/org/springframework/batch/restart/Restartable.java
index 9f5177d38..b97db108b 100644
--- a/infrastructure/src/main/java/org/springframework/batch/restart/Restartable.java
+++ b/infrastructure/src/main/java/org/springframework/batch/restart/Restartable.java
@@ -16,10 +16,41 @@
 
 package org.springframework.batch.restart;
 
-
+/**
+ * <p>Marker interface defining a contract for periodically storing
+ * state and restoring from that state should an error occur.
+ * <p>
+ *
+ * <p>The state that is stored is represented as {@link RestartData}
+ * which enforces a requirement that any restart data can be represented
+ * by a Properties object.  In general, the contract is that RestartData
+ * that is returned via the getRestartData method will be given back to
+ * the restoreFrom method, exactly as it was provided.  However, since
+ * it is primarily stored in a database, there is almost no way to know
+ * the whether a blank column in the database refers to null data,
+ * null properties, or empty properties.  Therefore, any class implementing
+ * this interface should assume that no restart data is equivalent to
+ * data with empty Properties.
+ * </p>
+ *
+ * @author Lucas Ward
+ *
+ */
 public interface Restartable {
 
+	/**
+	 * Get RestartData representing this object's current state.  Ideally,
+	 * if no state should be stored, RestartData.getProperties should return
+	 * an empty Properties object.
+	 *
+	 * @return RestartData representing current state.
+	 */
 	RestartData getRestartData();
 
+	/**
+	 * Restart state given the provided RestartData.
+	 *
+	 * @param data
+	 */
 	void restoreFrom(RestartData data);
 }