Merge pull request #268 from prashanthjos/master

Collector Context changes to handle simple Objects

Author: stevehu

doc/collector_context.md

@@ -1,41 +1,106 @@
 ### CollectorContext
 
 
-There could be usecases where we want collect the information while we are validating the data. A simple example could be fetching some value from a database or from a microservice based on the data (which could be a text or a JSON object) in a given JSON node and the schema keyword we are using. 
+There could be usecases where we want collect the information while we are validating the data. A simple example could be fetching some value from a database or from a microservice based on the data (which could be a text or a JSON object. It should be noted that this should be a simple operation or validation might take more time to complete.) in a given JSON node and the schema keyword we are using. 
 
 The fetched data can be stored some where so that it can be used later after the validation is done. Since the current validation logic already parses the data and schema, both validation and collecting the required information can be done in one go.
 
-CollectorContext and Collector classes are designed to satisfy this usage.
+CollectorContext and Collector classes are designed to work with this usecase.
 
 #### How to use CollectorContext
 
-Objects of CollectorContext live on ThreadLocal which is unique for every thread. This allows users to add objects to context at many points in the framework like Formats,Keywords,Validators etc.
+Objects of CollectorContext live on ThreadLocal which is unique for every thread. This allows users to add objects to context at many points in the framework like Formats,Validators (Effectively CollectorContext can be used at any touch point in the validateAndCollect method thread call).
 
 CollectorContext instance can be obtained by calling the getInstance static method on CollectorContext.This method gives an instance from the ThreadLocal for the current thread.
 
 Collectors are added to CollectorContext. Collectors allows to collect the objects. A Collector is added to CollectorContext with a name and corresponding Collector instance.
 
 ```
 CollectorContext collectorContext = CollectorContext.getInstance();
-			collectorContext.add(SAMPLE_COLLECTOR_TYPE, new Collector<List<String>>() {
-				@Override
-				public List<String> collect() {
-					List<String> references = new ArrayList<String>();
-					references.add(getDatasourceMap().get(node.textValue()));
-					return references;
-				}
-			});
+collectorContext.add(SAMPLE_COLLECTOR_NAME, new Collector<List<String>>() {
+	@Override
+	public List<String> collect() {
+		List<String> references = new ArrayList<String>();
+		references.add(getDatasourceMap().get(node.textValue()));
+		return references;
+	}
+});
 ```
 
-To validate the schema with the ability to use CollectorContext, validateAndCollect method has to be invoked on the JsonSchema class. This class returns a ValidationResult that contains the errors encountered during validation and a CollectorContext instance. Objects constructed by Collectors can be retrieved from CollectorContext by using the name they were added with.
+However there might be usecases where we want to add a simple Object like String,Integer, etc into the Context. This can be done the same way a collector is added to the context.
+
+```
+CollectorContext collectorContext = CollectorContext.getInstance();
+collectorContext.add(SAMPLE_COLLECTOR,"sample-string")
+
+```
+
+To validate the schema with the ability to use CollectorContext, validateAndCollect method has to be invoked on the JsonSchema class. This class returns a ValidationResult that contains the errors encountered during validation and a CollectorContext instance. Objects constructed by Collectors or directly added to CollectorContext can be retrieved from CollectorContext by using the name they were added with.
 
 
 ```
  ValidationResult validationResult = jsonSchema.validateAndCollect(jsonNode);
  CollectorContext context = validationResult.getCollectorContext();
- List<String> contextValue = (List<String>)context.get(SAMPLE_COLLECTOR_TYPE);
+ List<String> contextValue = (List<String>)context.get(SAMPLE_COLLECTOR);
  
 ```
 
-Note that CollectorContext will be removed from ThreadLocal once validateAndCollect method returns. Also the data is loaded into CollectorContext only after all the validations are done.
+Note that CollectorContext will be removed from ThreadLocal once validateAndCollect method returns. Also the data collected by Collectors is loaded into CollectorContext only after all the validations are done.
+
+There might be usecases where a collector needs to collect the data at multiple touch points. For example one usecase might be collecting data in a validator and a formatter.If you are using a Collector rather than a Object, the combine method of the Collector allows to define how we want to combine the data into existing Collector.CollectorContext combineWithCollector method calls the combine method on the Collector. User just needs to call the CollectorContext combineWithCollector method every time some data needs to merged into existing Collector. The collect method on the Collector is called by the framework at the end of validation to return the data that was collected.
+
+```
+ class CustomCollector implements Collector<List<String>> {
+
+	List<String> returnList = new ArrayList<String>();
+
+	private Map<String, String> referenceMap = null;
+
+	public CustomCollector() {
+		referenceMap = getDatasourceMap();
+	}
+
+	@Override
+	public List<String> collect() {
+		return returnList;
+	}
+
+	@Override
+	public void combine(Object object) {
+		returnList.add(referenceMap.get((String) object));
+	}
+}
+
+CollectorContext collectorContext = CollectorContext.getInstance();
+if (collectorContext.get(SAMPLE_COLLECTOR) == null) {
+	collectorContext.add(SAMPLE_COLLECTOR, new CustomCollector());
+}
+collectorContext.combineWithCollector(SAMPLE_COLLECTOR, node.textValue());
+
+```
+
+One important thing to note when using Collectors is if we call get method on CollectorContext before the validation is complete, We would get back a Collector instance that was added to CollectorContext.
+
+```
+// Returns Collector before validation is done.
+Collector<List<String>> collector = collectorContext.get(SAMPLE_COLLECTOR);
+
+// Returns data collected by Collector after the validation is done.
+List<String> data = collectorContext.get(SAMPLE_COLLECTOR);
+
+```
+
+If you are using simple objects and if the data needs to be collected from multiple touch points, logic is straightforward as shown.
+
+```
+
+CollectorContext collectorContext = CollectorContext.getInstance();
+// If collector name is not added to context add one.
+if (collectorContext.get(SAMPLE_COLLECTOR) == null) {
+	collectorContext.add(SAMPLE_COLLECTOR, new ArrayList<String>());
+}
+// In this case we are adding a list to CollectorContext.
+List<String> returnList = (List<String>) collectorContext.get(SAMPLE_COLLECTOR);
+
+```
 

src/main/java/com/networknt/schema/AbstractCollector.java

@@ -0,0 +1,9 @@
+package com.networknt.schema;
+
+public abstract class AbstractCollector<E> implements Collector<E>{
+
+	@Override
+	public void combine(Object object) {
+		// Do nothing. This is the default Implementation.
+	}
+}

src/main/java/com/networknt/schema/Collector.java

@@ -8,6 +8,21 @@
  */
 public interface Collector<E> {
 
-    public E collect();
+
+	/**
+	 * This method should be called by the intermediate touch points that want to
+	 * combine the data being collected by this collector. This is an optional
+	 * method and could be used when the same collector is used for collecting data
+	 * at multiple touch points or accumulating data at same touch point.
+	 */
+	public void combine(Object object);
+
+	/**
+	 * Final method called by the framework that returns the actual collected data.
+	 * If the collector is not accumulating data or being used to collect data at
+	 * multiple touch points, only this method can be implemented.
+	 */
+	public E collect();
+
 
 }

src/main/java/com/networknt/schema/CollectorContext.java

@@ -3,57 +3,113 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.Set;
 
 /**
  * Context for holding the output returned by the {@link Collector}
  * implementations.
  */
 public class CollectorContext {
 
-    static final String COLLECTOR_CONTEXT_THREAD_LOCAL_KEY = "COLLECTOR_CONTEXT_THREAD_LOCAL_KEY";
-
-    // Get an instance from thread info (which uses ThreadLocal).
-    public static CollectorContext getInstance() {
-        return (CollectorContext) ThreadInfo.get(COLLECTOR_CONTEXT_THREAD_LOCAL_KEY);
-    }
-
-    /**
-     * Map for holding the collector type and {@link Collector}
-     */
-    private Map<String, Collector<?>> collectorMap = new HashMap<String, Collector<?>>();
-
-    /**
-     * Map for holding the collector type and {@link Collector} class collect method
-     * output.
-     */
-    private Map<String, Object> collectorLoadMap = new HashMap<String, Object>();
-
-    public <E> void add(String collectorType, Collector<E> collector) {
-        collectorMap.put(collectorType, collector);
-    }
-
-    public Object get(String collectorType) {
-        if (collectorLoadMap.get(collectorType) == null && collectorMap.get(collectorType) != null) {
-            collectorLoadMap.put(collectorType, collectorMap.get(collectorType).collect());
-        }
-        return collectorLoadMap.get(collectorType);
-    }
-
-    /**
-     * Load all the collectors associated with the context.
-     */
-    void load() {
-        for (Entry<String, Collector<?>> collectorEntrySet : collectorMap.entrySet()) {
-            collectorLoadMap.put(collectorEntrySet.getKey(), collectorEntrySet.getValue().collect());
-        }
-    }
-
-    /**
-     * Reset the context
-     */
-    void reset() {
-        this.collectorMap = new HashMap<String, Collector<?>>();
-        this.collectorLoadMap = new HashMap<String, Object>();
-    }
+	// Using a namespace string as key in ThreadLocal so that it is unique in
+	// ThreadLocal.
+	static final String COLLECTOR_CONTEXT_THREAD_LOCAL_KEY = "com.networknt.schema.CollectorKey";
+
+	// Get an instance from thread info (which uses ThreadLocal).
+	public static CollectorContext getInstance() {
+		return (CollectorContext) ThreadInfo.get(COLLECTOR_CONTEXT_THREAD_LOCAL_KEY);
+	}
+
+	/**
+	 * Map for holding the name and {@link Collector} or a simple Object.
+	 */
+	private Map<String, Object> collectorMap = new HashMap<String, Object>();
+
+	/**
+	 * Map for holding the name and {@link Collector} class collect method output.
+	 */
+	private Map<String, Object> collectorLoadMap = new HashMap<String, Object>();
+
+	/**
+	 * 
+	 * Adds a collector with give name. Preserving this method for backward
+	 * compatibility.
+	 * 
+	 * @param <E>
+	 * @param name
+	 * @param collector
+	 */
+	public <E> void add(String name, Collector<E> collector) {
+		collectorMap.put(name, collector);
+	}
+
+	/**
+	 * 
+	 * Adds a collector or a simple object with give name.
+	 * 
+	 * @param <E>
+	 * @param name
+	 * @param collector
+	 */
+	public <E> void add(String name, Object object) {
+		collectorMap.put(name, object);
+	}
+
+	/**
+	 * 
+	 * Gets the data associated with a given name. Please note if you are using a
+	 * Collector you should wait till the validation is complete to gather all data.
+	 * 
+	 * For a Collector, this method will return the collector as long as load method
+	 * is not called. Once the load method is called this method will return the
+	 * actual data collected by collector.
+	 * 
+	 * @param name
+	 * @return
+	 */
+	public Object get(String name) {
+		Object object = collectorMap.get(name);
+		if (object instanceof Collector<?> && (collectorLoadMap.get(name) != null)) {
+			return collectorLoadMap.get(name);
+		}
+		return collectorMap.get(name);
+	}
+
+	/**
+	 * 
+	 * Combines data with Collector identified by the given name.
+	 * 
+	 * @param name
+	 * @param data
+	 */
+	public void combineWithCollector(String name, Object data) {
+		Object object = collectorMap.get(name);
+		if (object instanceof Collector<?>) {
+			Collector<?> collector = (Collector<?>) object;
+			collector.combine(data);
+		}
+	}
+
+	/**
+	 * Reset the context
+	 */
+	void reset() {
+		this.collectorMap = new HashMap<String, Object>();
+		this.collectorLoadMap = new HashMap<String, Object>();
+	}
+
+	/**
+	 * Loads data from all collectors.
+	 */
+	void loadCollectors() {
+		Set<Entry<String, Object>> entrySet = collectorMap.entrySet();
+		for (Entry<String, Object> entry : entrySet) {
+			if (entry.getValue() instanceof Collector<?>) {
+				Collector<?> collector = (Collector<?>) entry.getValue();
+				collectorLoadMap.put(entry.getKey(), collector.collect());
+			}
+		}
+
+	}
 
 }

src/main/java/com/networknt/schema/JsonSchema.java

@@ -216,31 +216,31 @@ public ValidationResult validateAndCollect(JsonNode node) {
         return validateAndCollect(node, node, AT_ROOT);
     }
 
-
-    /**
-     * This method both validates and collects the data in a CollectionContext.
-     *
-     * @param jsonNode JsonNode
-     * @param rootNode JsonNode
-     * @param at String of path
-     * @return ValidationResult
-     */
-    protected ValidationResult validateAndCollect(JsonNode jsonNode, JsonNode rootNode, String at) {
-        try {
-            // Create the collector context object.
-            CollectorContext collectorContext = new CollectorContext();
-            // Set the collector context in thread info, this is unique for every thread.
-            ThreadInfo.set(CollectorContext.COLLECTOR_CONTEXT_THREAD_LOCAL_KEY, collectorContext);
-            Set<ValidationMessage> errors = validate(jsonNode, rootNode, at);
-            // Load all the data from collectors into the context.
-            collectorContext.load();
-            // Collect errors and collector context into validation result.
-            ValidationResult validationResult = new ValidationResult(errors, collectorContext);
-            return validationResult;
-        } finally {
-            ThreadInfo.remove(CollectorContext.COLLECTOR_CONTEXT_THREAD_LOCAL_KEY);
-        }
-    }
+    
+	/**
+	 * 
+	 * This method both validates and collects the data in a CollectionContext.
+	 * @param jsonNode
+	 * @param rootNode
+	 * @param at
+	 * @return
+	 */
+	protected ValidationResult validateAndCollect(JsonNode jsonNode, JsonNode rootNode, String at) {
+		try {
+			// Create the collector context object.
+			CollectorContext collectorContext = new CollectorContext();
+			// Set the collector context in thread info, this is unique for every thread.
+			ThreadInfo.set(CollectorContext.COLLECTOR_CONTEXT_THREAD_LOCAL_KEY, collectorContext);
+			Set<ValidationMessage> errors = validate(jsonNode, rootNode, at);
+			// Load all the data from collectors into the context.
+			collectorContext.loadCollectors();
+			// Collect errors and collector context into validation result.
+			ValidationResult validationResult = new ValidationResult(errors, collectorContext);
+			return validationResult;
+		} finally {
+			ThreadInfo.remove(CollectorContext.COLLECTOR_CONTEXT_THREAD_LOCAL_KEY);
+		}
+	}
 
     @Override
     public String toString() {
@@ -254,5 +254,9 @@ public boolean hasRequiredValidator() {
     public JsonValidator getRequiredValidator() {
         return requiredValidator;
     }
+    
+    public Map<String, JsonValidator> getValidators() {
+    	return validators;
+    }
 
 }

src/main/java/com/networknt/schema/JsonSchemaFactory.java

@@ -237,7 +237,7 @@ public static Builder builder(final JsonSchemaFactory blueprint) {
         return builder;
     }
 
-    private JsonSchema newJsonSchema(final URI schemaUri, final JsonNode schemaNode, final SchemaValidatorsConfig config) {
+    protected JsonSchema newJsonSchema(final URI schemaUri, final JsonNode schemaNode, final SchemaValidatorsConfig config) {
         final ValidationContext validationContext = createValidationContext(schemaNode);
         validationContext.setConfig(config);
         JsonSchema jsonSchema = new JsonSchema(validationContext, schemaUri, schemaNode);