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);