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..545112ba8a2 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,31 @@
import java.io.StringWriter;
import java.io.Writer;
-// TODO: Document
+/**
+ * GsonSerializer provides the ability to serialize and deserialize objects to and from JSON
+ *
+ * Serialized JSON 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();
}
+ /**
+ * 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
+ * @return contents of the JSON as a string
+ */
public String toJson(T object, TypeHandler typeHandler) {
StringWriter writer = new StringWriter();
@@ -52,47 +69,112 @@ public String toJson(T object, TypeHandler typeHandler) {
return writer.toString();
}
+ /**
+ * 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
+ * @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 the {@link OutputStream} as JSON.
+ *
+ * @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 the {@link File} as JSON.
+ *
+ * @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 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
+ * @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 the {@link Reader}'s contents.
+ *
+ * @see #persistedDataFromJson(InputStream)
+ * @param reader Reader object that contains the contents 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 {@link InputStream}'s contents.
+ *
+ * @see #persistedDataFromJson(Reader)
+ * @param stream Contents of the InputStream 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 {@link File} object's contents.
+ *
+ * @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 from a {@link String}'s contents.
+ *
+ * @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);