add API Doc to deserialize package

celadari · celadari · commit ccddf2e679fd · 2021-11-23T20:38:58.000+01:00
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/Deserializer.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/Deserializer.scala
@@ -1,3 +1,4 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize
 
 import play.api.libs.json.{JsArray, JsLookupResult, JsNull, JsObject, JsValue}
@@ -7,8 +8,18 @@ import com.celadari.jsonlogicscala.tree.types.{AnyTypeValue, ArrayTypeValue, Map
 import com.celadari.jsonlogicscala.tree.{ComposeLogic, JsonLogicCore, ValueLogic}
 
 
+/**
+ * Companion object holding implicit deserializer.
+ * Useful to invoke methods using implicit [[com.celadari.jsonlogicscala.deserialize.Deserializer]] that do not require
+ * custom Deserializer.
+ */
 object Deserializer {
 
+  /**
+   * Returns [[com.celadari.jsonlogicscala.tree.types.TypeValue]] from json input.
+   * @param jsLookupResult: input json representing a type.
+   * @return TypeValue.
+   */
   def unmarshType(jsLookupResult: JsLookupResult): Option[TypeValue] = {
     if (jsLookupResult.isDefined) {
       try {
@@ -23,10 +34,33 @@ object Deserializer {
   implicit val defaultDeserializer: Deserializer = new Deserializer()
 }
 
+/**
+ * Responsible for deserializing json into scala [[com.celadari.jsonlogicscala.tree.JsonLogicCore]] data structure.
+ * May be extended to fit custom use cases. Providing the right configuration via
+ * [[com.celadari.jsonlogicscala.deserialize.DeserializerConf]] is enough to cover most cases.
+ * You may redefine methods to handle extreme uncommon cases.
+ * @param conf: informs of mappings (type_codename -> unmarshaller).
+ */
 class Deserializer(implicit val conf: DeserializerConf) {
+  /**
+   * Maps type_codename to [[com.celadari.jsonlogicscala.deserialize.Unmarshaller]].
+   * @note More specifically, keys should be type_codename of [[com.celadari.jsonlogicscala.tree.types.SimpleTypeValue]]
+   * as generic types (OptionTypeValue, MapTypeValue, ArrayTypeValue) are handled recursively by getMarshaller.
+   */
   protected[this] val unmarshallers: Map[String, Unmarshaller] = if (conf.isPriorityToManualAdd) conf.unmarshallerMetaInfAdd ++ conf.unmarshallersManualAdd
                                                                  else conf.unmarshallersManualAdd ++ conf.unmarshallerMetaInfAdd
 
+  /**
+   * Returns [[com.celadari.jsonlogicscala.deserialize.Unmarshaller]] associated with input typeValue.
+   * If input typeValue is [[com.celadari.jsonlogicscala.tree.types.SimpleTypeValue]] then returns mapped value
+   * by unmarshallers attribute.
+   * If input typeValue is [[com.celadari.jsonlogicscala.tree.types.OptionTypeValue]],
+   * [[com.celadari.jsonlogicscala.tree.types.ArrayTypeValue]], [[com.celadari.jsonlogicscala.tree.types.MapTypeValue]]
+   * then a new [[com.celadari.jsonlogicscala.deserialize.Unmarshaller]] is recursively created by checking paramType of
+   * input typeValue.
+   * @param typeValue: input type to return associated Unmarshaller.
+   * @return Unmarshaller associated to typeValue.
+   */
   protected[this] def getUnmarshaller(typeValue: TypeValue): Unmarshaller = {
     typeValue match {
       case SimpleTypeValue(codename) => unmarshallers.getOrElse(codename, throw new IllegalInputException(s"No unmarshaller defined for $codename"))
@@ -50,6 +84,12 @@ class Deserializer(implicit val conf: DeserializerConf) {
     }
   }
 
+  /**
+   * Returns [[com.celadari.jsonlogicscala.tree.ValueLogic]] by combining logic from jsonLogic and data from jsonLogicData.
+   * @param jsonLogic: logic.
+   * @param jsonLogicData: data values.
+   * @return ValueLogic.
+   */
   protected[this] def deserializeValueLogic(jsonLogic: JsObject, jsonLogicData: JsObject): ValueLogic[_] = {
     val isTypeDefined = (jsonLogic \ "type").isDefined
     val typeValueOpt = Deserializer.unmarshType(jsonLogic \ "type")
@@ -73,6 +113,12 @@ class Deserializer(implicit val conf: DeserializerConf) {
     ValueLogic(valueOpt, typeValueOpt, variableNameOpt, pathDataOpt)
   }
 
+  /**
+   * Returns [[com.celadari.jsonlogicscala.tree.ComposeLogic]] by combining logic from jsonLogic and data from jsonLogicData.
+   * @param jsonLogic: logic.
+   * @param jsonLogicData: data values.
+   * @return ComposeLogic.
+   */
   protected[this] def deserializeComposeLogic(jsonLogic: JsObject, jsonLogicData: JsObject): ComposeLogic = {
     // check for operator field
     val fields = jsonLogic.fields
@@ -90,6 +136,13 @@ class Deserializer(implicit val conf: DeserializerConf) {
     new ComposeLogic(operator, deserializeArrayOfConditions((jsonLogic \ operator).get, jsonLogicData))
   }
 
+  /**
+   * Returns array of [[com.celadari.jsonlogicscala.tree.JsonLogicCore]] from tuple of serialized (logic, data).
+   * Logic is assumed to be an array of JsValue (JsArray) and each member of array is deserialized.
+   * @param json: JsValue representing array of logics.
+   * @param jsonLogicData: data values.
+   * @return array of [[com.celadari.jsonlogicscala.tree.JsonLogicCore]].
+   */
   protected[this] def deserializeArrayOfConditions(json: JsValue, jsonLogicData: JsObject): Array[JsonLogicCore] = {
     val jsArray = json.asInstanceOf[JsArray]
     jsArray
@@ -100,6 +153,12 @@ class Deserializer(implicit val conf: DeserializerConf) {
       .toArray
   }
 
+  /**
+   * Returns [[com.celadari.jsonlogicscala.tree.JsonLogicCore]] by combining logic from jsonLogic and data from jsonLogicData.
+   * @param jsonLogic: logic.
+   * @param jsonLogicData: data values.
+   * @return JsonLogicCore.
+   */
   // scalastyle:off return
   def deserialize(jsonLogic: JsObject, jsonLogicData: JsObject): JsonLogicCore = {
     // check for operator field
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/DeserializerConf.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/DeserializerConf.scala
@@ -1,3 +1,4 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize
 
 import org.apache.xbean.finder.ResourceFinder
@@ -7,7 +8,14 @@ import com.celadari.jsonlogicscala.configuration.ConfigurationFetcher
 import com.celadari.jsonlogicscala.deserialize.defaults._
 
 
+/**
+ * Companion object to hold implicit: [[com.celadari.jsonlogicscala.deserialize.DeserializerConf]], mapping of default
+ * unmarshallers (type_codename -> Unmarshaller), method to create a custom configuration.
+ */
 object DeserializerConf {
+  /**
+   * Maps default type_codenames to default unmarshallers.
+   */
   val DEFAULT_UNMARSHALLERS: Map[String, Unmarshaller] = Map(
     BOOL_CODENAME -> UnmarshallerBoolean,
     DOUBLE_CODENAME -> UnmarshallerDouble,
@@ -20,6 +28,13 @@ object DeserializerConf {
     NULL_CODENAME -> UnmarshallerNull
   )
 
+  /**
+   * Returns a custom deserializer configuration.
+   * @param path: folder to provider-configuration files.
+   * @param unmarshallersManualAdd: map of (type_codename -> Unmashaller) to be added to the deserializer configuration.
+   * @param isPriorityToManualAdd: boolean indicating if unmarshallers manually added have priority over those fetched from provider-configuration folder.
+   * @return custom deserializer configuration.
+   */
   def createConf(
                   path: String = "META-INF/services/",
                   unmarshallersManualAdd: Map[String, Unmarshaller] = DEFAULT_UNMARSHALLERS,
@@ -34,6 +49,13 @@ object DeserializerConf {
   implicit val deserializerConf: DeserializerConf = createConf()
 }
 
+/**
+ * Represents a deserializer's configuration.
+ * It informs the deserializer how to map a type_codename to a [[com.celadari.jsonlogicscala.deserialize.Unmarshaller]].
+ * @param unmarshallerMetaInfAdd: map of (type_codename -> Unmarshaller) fetched from META-INF resources folder.
+ * @param unmarshallersManualAdd: map of (type_codename -> Unmarshaller) manually added to the configuration.
+ * @param isPriorityToManualAdd: boolean indicating if unmarshallers manually added have priority over those fetched from META-INF folder.
+ */
 case class DeserializerConf(
                              unmarshallerMetaInfAdd: Map[String, Unmarshaller],
                              unmarshallersManualAdd: Map[String, Unmarshaller],
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/Unmarshaller.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/Unmarshaller.scala
@@ -1,10 +1,23 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize
 
 import scala.reflect.runtime.{universe => ru}
 import play.api.libs.json.JsValue
 
 
+/**
+ * Defines interface of class/object defining unmarshal method.
+ * This method deserializes a specific scala data structure to json format.
+ */
 trait Unmarshaller {
+
+  /**
+   * Deserializes a json to a specific scala data structure.
+   * @param jsValue: json to be deserialized into scala data structure.
+   * @return scala data structure value.
+   * @note serialized value of basic types (Int, String, Boolean, ...) are the values themselves, custom defined classes
+   * are usually serialized to map of (attribute -> value).
+   */
   def unmarshal(jsValue: JsValue): Any
 
   // scalastyle:off return
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerBoolean.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerBoolean.scala
@@ -1,11 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsBoolean, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format boolean value to scala boolean value.
+ */
 object UnmarshallerBoolean extends Unmarshaller {
+
+  /**
+   * Converts json boolean value to scala boolean value.
+   * @param jsValue: json to deserialized to Boolean value.
+   * @return scala boolean value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsBoolean(bool) => bool
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerByte.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerByte.scala
@@ -1,11 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format byte value to scala byte value.
+ */
 object UnmarshallerByte extends Unmarshaller{
+
+  /**
+   * Converts json byte value to scala byte value.
+   * @param jsValue: json to deserialized to Byte value.
+   * @return scala byte value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toByte
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerDouble.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerDouble.scala
@@ -1,11 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format double value to scala double value.
+ */
 object UnmarshallerDouble extends Unmarshaller{
+
+  /**
+   * Converts json double value to scala double value.
+   * @param jsValue: json to deserialized to Double value.
+   * @return scala double value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toDouble
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerFloat.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerFloat.scala
@@ -1,11 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format float value to scala float value.
+ */
 object UnmarshallerFloat extends Unmarshaller{
+
+  /**
+   * Converts json float value to scala float value.
+   * @param jsValue: json to deserialized to Float value.
+   * @return scala float value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toFloat
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerInt.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerInt.scala
@@ -1,10 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
+
+/**
+ * Default unmarshaller that converts json format int value to scala int value.
+ */
 object UnmarshallerInt extends Unmarshaller{
+
+  /**
+   * Converts json int value to scala int value.
+   * @param jsValue: json to deserialized to Int value.
+   * @return scala int value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toInt
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerLong.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerLong.scala
@@ -1,11 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format long value to scala long value.
+ */
 object UnmarshallerLong extends Unmarshaller{
+
+  /**
+   * Converts json long value to scala long value.
+   * @param jsValue: json to deserialized to Long value.
+   * @return scala long value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toLong
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerNull.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerNull.scala
@@ -1,12 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNull, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format null value to scala null value.
+ */
 object UnmarshallerNull extends Unmarshaller {
 
+  /**
+   * Converts json null value to scala null value.
+   * @param jsValue: json to deserialized to Null value.
+   * @return scala null value.
+   */
   // scalastyle:off null
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerShort.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerShort.scala
@@ -1,12 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsNumber, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
 
+/**
+ * Default unmarshaller that converts json format short value to scala short value.
+ */
 object UnmarshallerShort extends Unmarshaller{
 
+  /**
+   * Converts json short value to scala short value.
+   * @param jsValue: json to deserialized to Short value.
+   * @return scala short value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsNumber(num) => num.toShort
diff --git a/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerString.scala b/src/main/scala/com/celadari/jsonlogicscala/deserialize/defaults/UnmarshallerString.scala
@@ -1,10 +1,21 @@
+// Copyright 2019 celadari. All rights reserved. MIT license.
 package com.celadari.jsonlogicscala.deserialize.defaults
 
 import play.api.libs.json.{JsString, JsValue}
 import com.celadari.jsonlogicscala.deserialize.Unmarshaller
 import com.celadari.jsonlogicscala.exceptions.InvalidJsonParsingException
 
+
+/**
+ * Default unmarshaller that converts json format string value to scala string value.
+ */
 object UnmarshallerString extends Unmarshaller{
+
+  /**
+   * Converts json string value to scala string value.
+   * @param jsValue: json to deserialized to String value.
+   * @return scala string value.
+   */
   def unmarshal(jsValue: JsValue): Any = {
     jsValue match {
       case JsString(string) => string
