Add additional encode and decode methods to Coder

Also:
Updated some comments and renamed a few parameters.
Removed a "throws" for a RuntimeException.

Short-circuit some calls.

Typo in comment.
Let gson create the JsonWriter.
Renamed a few more parameters.

Change-Id: I22e48c2191820c2a3d0743200edca79bd74353e7
Issue-ID: POLICY-1444
Signed-off-by: Jim Hahn <jrh3@att.com>

2 files changed, 206 insertions, 1 deletions

diff --git a/utils/src/main/java/org/onap/policy/common/utils/coder/Coder.java b/utils/src/main/java/org/onap/policy/common/utils/coder/Coder.java
index 41db218b..66a308f7 100644
--- a/utils/src/main/java/org/onap/policy/common/utils/coder/Coder.java
+++ b/utils/src/main/java/org/onap/policy/common/utils/coder/Coder.java
@@ -20,6 +20,12 @@
 
 package org.onap.policy.common.utils.coder;
 
+import java.io.File;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Reader;
+import java.io.Writer;
+
 /**
  * JSON encoder and decoder.
  */
@@ -35,7 +41,34 @@ public interface Coder {
     String encode(Object object) throws CoderException;
 
     /**
-     * Decodes a json string into an object.
+     * Encodes an object into json, writing to the given target.
+     *
+     * @param target target to which to write the encoded json
+     * @param object object to be encoded
+     * @throws CoderException if an error occurs
+     */
+    void encode(Writer target, Object object) throws CoderException;
+
+    /**
+     * Encodes an object into json, writing to the given target.
+     *
+     * @param target target to which to write the encoded json
+     * @param object object to be encoded
+     * @throws CoderException if an error occurs
+     */
+    void encode(OutputStream target, Object object) throws CoderException;
+
+    /**
+     * Encodes an object into json, writing to the given target.
+     *
+     * @param target target to which to write the encoded json
+     * @param object object to be encoded
+     * @throws CoderException if an error occurs
+     */
+    void encode(File target, Object object) throws CoderException;
+
+    /**
+     * Decodes json into an object.
      *
      * @param json json string to be decoded
      * @param clazz class of object to be decoded
@@ -43,4 +76,34 @@ public interface Coder {
      * @throws CoderException if an error occurs
      */
     <T> T decode(String json, Class<T> clazz) throws CoderException;
+
+    /**
+     * Decodes json into an object, reading it from the given source.
+     *
+     * @param source source from which to read the json string to be decoded
+     * @param clazz class of object to be decoded
+     * @return the object represented by the given json string
+     * @throws CoderException if an error occurs
+     */
+    <T> T decode(Reader source, Class<T> clazz) throws CoderException;
+
+    /**
+     * Decodes json into an object, reading it from the given source.
+     *
+     * @param source source from which to read the json string to be decoded
+     * @param clazz class of object to be decoded
+     * @return the object represented by the given json string
+     * @throws CoderException if an error occurs
+     */
+    <T> T decode(InputStream source, Class<T> clazz) throws CoderException;
+
+    /**
+     * Decodes json into an object, reading it from the given source.
+     *
+     * @param source source from which to read the json string to be decoded
+     * @param clazz class of object to be decoded
+     * @return the object represented by the given json string
+     * @throws CoderException if an error occurs
+     */
+    <T> T decode(File source, Class<T> clazz) throws CoderException;
 }
diff --git a/utils/src/main/java/org/onap/policy/common/utils/coder/StandardCoder.java b/utils/src/main/java/org/onap/policy/common/utils/coder/StandardCoder.java
index 4c7a55c2..389720f9 100644
--- a/utils/src/main/java/org/onap/policy/common/utils/coder/StandardCoder.java
+++ b/utils/src/main/java/org/onap/policy/common/utils/coder/StandardCoder.java
@@ -21,6 +21,18 @@
 package org.onap.policy.common.utils.coder;
 
 import com.google.gson.Gson;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.io.Reader;
+import java.io.Writer;
+import java.nio.charset.StandardCharsets;
 
 /**
  * JSON encoder and decoder using the "standard" mechanism, which is currently gson.
@@ -50,6 +62,42 @@ public class StandardCoder implements Coder {
     }
 
     @Override
+    public void encode(Writer target, Object object) throws CoderException {
+        try {
+            toJson(target, object);
+
+        } catch (RuntimeException | IOException e) {
+            throw new CoderException(e);
+        }
+    }
+
+    @Override
+    public void encode(OutputStream target, Object object) throws CoderException {
+        try {
+            Writer wtr = makeWriter(target);
+            toJson(wtr, object);
+
+            // flush, but don't close
+            wtr.flush();
+
+        } catch (RuntimeException | IOException e) {
+            throw new CoderException(e);
+        }
+    }
+
+    @Override
+    public void encode(File target, Object object) throws CoderException {
+        try (Writer wtr = makeWriter(target)) {
+            toJson(wtr, object);
+
+            // no need to flush or close here
+
+        } catch (RuntimeException | IOException e) {
+            throw new CoderException(e);
+        }
+    }
+
+    @Override
     public <T> T decode(String json, Class<T> clazz) throws CoderException {
         try {
             return fromJson(json, clazz);
@@ -59,9 +107,81 @@ public class StandardCoder implements Coder {
         }
     }
 
+    @Override
+    public <T> T decode(Reader source, Class<T> clazz) throws CoderException {
+        try {
+            return fromJson(source, clazz);
+
+        } catch (RuntimeException e) {
+            throw new CoderException(e);
+        }
+    }
+
+    @Override
+    public <T> T decode(InputStream source, Class<T> clazz) throws CoderException {
+        try {
+            return fromJson(makeReader(source), clazz);
+
+        } catch (RuntimeException e) {
+            throw new CoderException(e);
+        }
+    }
+
+    @Override
+    public <T> T decode(File source, Class<T> clazz) throws CoderException {
+        try (Reader input = makeReader(source)) {
+            return fromJson(input, clazz);
+
+        } catch (RuntimeException | IOException e) {
+            throw new CoderException(e);
+        }
+    }
+
     // the remaining methods are wrappers that can be overridden by junit tests
 
     /**
+     * Makes a writer for the given file.
+     *
+     * @param target file of interest
+     * @return a writer for the file
+     * @throws FileNotFoundException if the file cannot be created
+     */
+    protected Writer makeWriter(File target) throws FileNotFoundException {
+        return makeWriter(new FileOutputStream(target));
+    }
+
+    /**
+     * Makes a writer for the given stream.
+     *
+     * @param target stream of interest
+     * @return a writer for the stream
+     */
+    protected Writer makeWriter(OutputStream target) {
+        return new OutputStreamWriter(target, StandardCharsets.UTF_8);
+    }
+
+    /**
+     * Makes a reader for the given file.
+     *
+     * @param source file of interest
+     * @return a reader for the file
+     * @throws FileNotFoundException if the file does not exist
+     */
+    protected Reader makeReader(File source) throws FileNotFoundException {
+        return makeReader(new FileInputStream(source));
+    }
+
+    /**
+     * Makes a reader for the given stream.
+     *
+     * @param source stream of interest
+     * @return a reader for the stream
+     */
+    protected Reader makeReader(InputStream source) {
+        return new InputStreamReader(source, StandardCharsets.UTF_8);
+    }
+
+    /**
      * Encodes an object into json, without catching exceptions.
      *
      * @param object object to be encoded
@@ -72,6 +192,17 @@ public class StandardCoder implements Coder {
     }
 
     /**
+     * Encodes an object into json, without catching exceptions.
+     *
+     * @param target target to which to write the encoded json
+     * @param object object to be encoded
+     * @throws IOException if an I/O error occurs
+     */
+    protected void toJson(Writer target, Object object) throws IOException {
+        GSON.toJson(object, object.getClass(), target);
+    }
+
+    /**
      * Decodes a json string into an object, without catching exceptions.
      *
      * @param json json string to be decoded
@@ -81,4 +212,15 @@ public class StandardCoder implements Coder {
     protected <T> T fromJson(String json, Class<T> clazz) {
         return GSON.fromJson(json, clazz);
     }
+
+    /**
+     * Decodes a json string into an object, without catching exceptions.
+     *
+     * @param source source from which to read the json string to be decoded
+     * @param clazz class of object to be decoded
+     * @return the object represented by the given json string
+     */
+    protected <T> T fromJson(Reader source, Class<T> clazz) {
+        return GSON.fromJson(source, clazz);
+    }
 }