From 5a45ebd5cb424f147b1d214522c730df943f6950 Mon Sep 17 00:00:00 2001 From: nschnitzer Date: Sun, 2 Dec 2018 09:49:04 -0500 Subject: [PATCH 1/5] Added Documentation to GsonSerializer.java --- .../serializers/GsonSerializer.java | 94 ++++++++++++++++++- 1 file changed, 89 insertions(+), 5 deletions(-) diff --git a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java index 3567f88c0c0..d5bfbd8af4a 100644 --- a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java +++ b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java @@ -36,14 +36,33 @@ import java.io.StringWriter; import java.io.Writer; -// TODO: Document +/** + * GsonSerializer provides the ability to serialize and deserialize between + * JSONs and Objects
+ *
+ * Serialized JSONs can be forwarded/written to various output types
+ *
+ * Various input types can be deserialized and returned as PersistedData types + * + */ public class GsonSerializer { private Gson gson; + /** + * Constructs a new GsonSerializer object + */ public GsonSerializer() { this.gson = new Gson(); } + /** + * Converts the object into an array of bytes and forwards it to + * {@link #writeJson(Object, TypeHandler, Writer)} + * + * @param object the object to be serialized + * @param typeHandler contains how the object will be serialized + * @return contents of the JSON as a string + */ public String toJson(T object, TypeHandler typeHandler) { StringWriter writer = new StringWriter(); @@ -52,47 +71,112 @@ public String toJson(T object, TypeHandler typeHandler) { return writer.toString(); } + /** + * Writes an object's serialized persisted data to a Writer + * + * @see #writeJson(Object, TypeHandler, OutputStream) + * @param object the object to be serialized + * @param typeHandler contains how the object will be serialized + * @param writer The writer in which the JSON will be written to + */ public void writeJson(T object, TypeHandler typeHandler, Writer writer) { - GsonPersistedData persistedData = - (GsonPersistedData) typeHandler.serialize(object, new GsonPersistedDataSerializer()); + GsonPersistedData persistedData = (GsonPersistedData) typeHandler.serialize(object, + new GsonPersistedDataSerializer()); gson.toJson(persistedData.getElement(), writer); } + /** + * Writes an object's serialized persisted data to an OutputStream + * + * @see #writeJson(Object, TypeHandler, Writer) + * @param object the object to be serialized + * @param typeHandler contains how the object will be serialized + * @param stream stream that the data will be written to + * @throws IOException will be thrown if there is an error writing to the stream + */ public void writeJson(T object, TypeHandler typeHandler, OutputStream stream) throws IOException { try (Writer writer = new BufferedWriter(new OutputStreamWriter(stream))) { writeJson(object, typeHandler, writer); } } + /** + * Writes the object's persisted data to a File object + * + * @see #writeJson(Object, TypeHandler, String) + * @param object the file to be serialized + * @param typeHandler contains how the object will be serialized + * @param file file that the bytes will be written to + * @throws IOException gets thrown if there is an issue writing to the file + */ public void writeJson(T object, TypeHandler typeHandler, File file) throws IOException { try (Writer writer = new BufferedWriter(new FileWriter(file))) { writeJson(object, typeHandler, writer); } } - public void writeJson(T object, TypeHandler typeHandler, String path) throws IOException { - writeJson(object, typeHandler, new File(path)); + /** + * Writes the a the object's persisted data to a File located at a specified file name + * + * @see #writeJson(Object, TypeHandler, String) + * @param object the object to be serialized + * @param typeHandler contains how the object will be serialized + * @param fileName the file name where the JSON will be written + * @throws IOException gets thrown if there is an error writing to the file at the specified location + */ + public void writeJson(T object, TypeHandler typeHandler, String fileName) throws IOException { + writeJson(object, typeHandler, new File(fileName)); } + /** + * Gets the PersistedData from a Reader object + * + * @see #persistedDataFromJson(InputStream) + * @param reader Reader object that will be deserialized + * @return deserialized GsonPersistedData object + */ public PersistedData persistedDataFromJson(Reader reader) { JsonElement jsonElement = gson.fromJson(reader, JsonElement.class); return new GsonPersistedData(jsonElement); } + /** + * Gets the PersistedData from an InputStream + * + * @see #persistedDataFromJson(Reader) + * @param stream the InputStream that will be serialized + * @return deserialized GsonPersistedData object + * @throws IOException if there is an issue parsing the stream + */ public PersistedData persistedDataFromJson(InputStream stream) throws IOException { try (Reader reader = new InputStreamReader(stream)) { return persistedDataFromJson(reader); } } + /** + * Gets the PersistedData from a File object + * + * @see #persistedDataFromJson(String) + * @param file File object containing the JSON that will be deserialized + * @return deserialized GsonPersistedData object + * @throws IOException gets thrown if there is an issue reading the File object + */ public PersistedData persistedDataFromJson(File file) throws IOException { try (Reader reader = new FileReader(file)) { return persistedDataFromJson(reader); } } + /** + * Gets the PersistedData by forwarding a Reader which contains a String to {@link #persistedDataFromJson(Reader)} + * + * @see #persistedDataFromJson(Reader) + * @param json the String that will be deserialized + * @return deserialized GsonPersistedData Object + */ public PersistedData persistedDataFromJson(String json) { try (StringReader reader = new StringReader(json)) { return persistedDataFromJson(reader); From 6c3fa136397f4f2b3a31f58130d56155a75d79f9 Mon Sep 17 00:00:00 2001 From: nschnitzer Date: Mon, 3 Dec 2018 17:50:22 -0500 Subject: [PATCH 2/5] Enhanced Gson Serializer --- .../serializers/GsonSerializer.java | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java index d5bfbd8af4a..4ad7699961e 100644 --- a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java +++ b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java @@ -56,8 +56,7 @@ public GsonSerializer() { } /** - * Converts the object into an array of bytes and forwards it to - * {@link #writeJson(Object, TypeHandler, Writer)} + * writes the serialized persisted data as a JSON to {@link Writer} and returns the JSON as a string. * * @param object the object to be serialized * @param typeHandler contains how the object will be serialized @@ -72,7 +71,7 @@ public String toJson(T object, TypeHandler typeHandler) { } /** - * Writes an object's serialized persisted data to a Writer + * Writes an object's serialized persisted data to the {@link Writer} as a JSON. * * @see #writeJson(Object, TypeHandler, OutputStream) * @param object the object to be serialized @@ -87,7 +86,7 @@ public void writeJson(T object, TypeHandler typeHandler, Writer writer) { } /** - * Writes an object's serialized persisted data to an OutputStream + * Writes an object's serialized persisted data to the {@link OutputStream} as a JSON. * * @see #writeJson(Object, TypeHandler, Writer) * @param object the object to be serialized @@ -102,7 +101,7 @@ public void writeJson(T object, TypeHandler typeHandler, OutputStream str } /** - * Writes the object's persisted data to a File object + * Writes the object's persisted data to the {@link File} as a JSON. * * @see #writeJson(Object, TypeHandler, String) * @param object the file to be serialized @@ -117,7 +116,7 @@ public void writeJson(T object, TypeHandler typeHandler, File file) throw } /** - * Writes the a the object's persisted data to a File located at a specified file name + * Writes the a the object's persisted data to {@link File} of a specified file name as a JSON * * @see #writeJson(Object, TypeHandler, String) * @param object the object to be serialized @@ -130,10 +129,10 @@ public void writeJson(T object, TypeHandler typeHandler, String fileName) } /** - * Gets the PersistedData from a Reader object + * Gets the PersistedData from the {@link Reader}'s contents. * * @see #persistedDataFromJson(InputStream) - * @param reader Reader object that will be deserialized + * @param reader Reader object that contains the contents that will be deserialized * @return deserialized GsonPersistedData object */ public PersistedData persistedDataFromJson(Reader reader) { @@ -143,10 +142,10 @@ public PersistedData persistedDataFromJson(Reader reader) { } /** - * Gets the PersistedData from an InputStream + * Gets the PersistedData from an {@link InputStream}'s contents. * * @see #persistedDataFromJson(Reader) - * @param stream the InputStream that will be serialized + * @param stream Contents of the InputStream will be serialized * @return deserialized GsonPersistedData object * @throws IOException if there is an issue parsing the stream */ @@ -157,7 +156,7 @@ public PersistedData persistedDataFromJson(InputStream stream) throws IOExceptio } /** - * Gets the PersistedData from a File object + * Gets the PersistedData from a {@link File} object's contents. * * @see #persistedDataFromJson(String) * @param file File object containing the JSON that will be deserialized @@ -171,7 +170,7 @@ public PersistedData persistedDataFromJson(File file) throws IOException { } /** - * Gets the PersistedData by forwarding a Reader which contains a String to {@link #persistedDataFromJson(Reader)} + * Gets the PersistedData from a {@link String}'s contents. * * @see #persistedDataFromJson(Reader) * @param json the String that will be deserialized From 66891728513c7acbab796019d734df82e978aae9 Mon Sep 17 00:00:00 2001 From: nschnitzer Date: Mon, 3 Dec 2018 17:52:49 -0500 Subject: [PATCH 3/5] Forgot one thing --- .../org/terasology/persistence/serializers/GsonSerializer.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java index 4ad7699961e..04ba3f991e0 100644 --- a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java +++ b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java @@ -37,8 +37,7 @@ import java.io.Writer; /** - * GsonSerializer provides the ability to serialize and deserialize between - * JSONs and Objects
+ * GsonSerializer provides the ability to serialize and deserialize objects to and from JSON *
* Serialized JSONs can be forwarded/written to various output types
*
From 0fbe65d10e50e33a03f04a9674bbb942cfb9ecb7 Mon Sep 17 00:00:00 2001 From: nschnitzer Date: Tue, 4 Dec 2018 18:28:47 -0500 Subject: [PATCH 4/5] Fixed Grammatical Errors --- .../persistence/serializers/GsonSerializer.java | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java index 04ba3f991e0..7c9a20f0ecd 100644 --- a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java +++ b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java @@ -55,7 +55,7 @@ public GsonSerializer() { } /** - * writes the serialized persisted data as a JSON to {@link Writer} and returns the JSON as a string. + * Writes the serialized persisted data as a JSON to {@link Writer} and returns the JSON as a string. * * @param object the object to be serialized * @param typeHandler contains how the object will be serialized @@ -70,7 +70,7 @@ public String toJson(T object, TypeHandler typeHandler) { } /** - * Writes an object's serialized persisted data to the {@link Writer} as a JSON. + * Writes an object's serialized persisted data to the {@link Writer} as JSON. * * @see #writeJson(Object, TypeHandler, OutputStream) * @param object the object to be serialized @@ -85,7 +85,7 @@ public void writeJson(T object, TypeHandler typeHandler, Writer writer) { } /** - * Writes an object's serialized persisted data to the {@link OutputStream} as a JSON. + * Writes an object's serialized persisted data to the {@link OutputStream} as JSON. * * @see #writeJson(Object, TypeHandler, Writer) * @param object the object to be serialized @@ -100,7 +100,7 @@ public void writeJson(T object, TypeHandler typeHandler, OutputStream str } /** - * Writes the object's persisted data to the {@link File} as a JSON. + * Writes the object's persisted data to the {@link File} as JSON. * * @see #writeJson(Object, TypeHandler, String) * @param object the file to be serialized @@ -115,7 +115,7 @@ public void writeJson(T object, TypeHandler typeHandler, File file) throw } /** - * Writes the a the object's persisted data to {@link File} of a specified file name as a JSON + * Writes the a the object's persisted data to {@link File} of a specified file name as JSON * * @see #writeJson(Object, TypeHandler, String) * @param object the object to be serialized From 8ca6bddad816cff6fbffdf1f68df4869aafa1f7f Mon Sep 17 00:00:00 2001 From: nschnitzer <33706405+nschnitzer@users.noreply.github.com> Date: Tue, 11 Dec 2018 13:47:37 -0500 Subject: [PATCH 5/5] Minor Grammatical Fixes --- .../terasology/persistence/serializers/GsonSerializer.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java index 7c9a20f0ecd..545112ba8a2 100644 --- a/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java +++ b/engine/src/main/java/org/terasology/persistence/serializers/GsonSerializer.java @@ -39,7 +39,7 @@ /** * GsonSerializer provides the ability to serialize and deserialize objects to and from JSON *
- * Serialized JSONs can be forwarded/written to various output types
+ * Serialized JSON can be forwarded/written to various output types
*
* Various input types can be deserialized and returned as PersistedData types * @@ -115,7 +115,7 @@ public void writeJson(T object, TypeHandler typeHandler, File file) throw } /** - * Writes the a the object's persisted data to {@link File} of a specified file name as JSON + * Writes an object's persisted data to {@link File} of a specified file name as JSON * * @see #writeJson(Object, TypeHandler, String) * @param object the object to be serialized