Skip to content

Commit f62fcd5

Browse files
celadariceladari
committed
add API Doc to serialize package
1 parent f3e6e79 commit f62fcd5

14 files changed

+171
-71
lines changed

‎scalastyle-config.xml‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,10 @@
88
</parameter>
99
</parameters>
1010
</check>
11-
<check class="org.scalastyle.file.HeaderMatchesChecker" level="warning" enabled="false">
11+
<check class="org.scalastyle.file.HeaderMatchesChecker" level="warning" enabled="true">
1212
<parameters>
1313
<parameter name="header">
14-
<![CDATA[//MIT License
15-
16-
//Copyright (c) 2019 celadari
17-
18-
Permission is hereby granted, free of charge, to any person obtaining a copy
19-
of this software and associated documentation files (the "Software"), to deal
20-
in the Software without restriction, including without limitation the rights
21-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
22-
copies of the Software, and to permit persons to whom the Software is
23-
furnished to do so, subject to the following conditions:
24-
25-
The above copyright notice and this permission notice shall be included in all
26-
copies or substantial portions of the Software.
27-
28-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
29-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
30-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
31-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
32-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
33-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
34-
SOFTWARE.]]>
14+
<![CDATA[// Copyright 2019 celadari. All rights reserved. MIT license.]]>
3515
</parameter>
3616
<parameter name="regex">
3717
<![CDATA[false]]>

‎scalastyle-test-config.xml‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -11,27 +11,7 @@
1111
<check class="org.scalastyle.file.HeaderMatchesChecker" level="warning" enabled="false">
1212
<parameters>
1313
<parameter name="header">
14-
<![CDATA[//MIT License
15-
16-
//Copyright (c) 2019 celadari
17-
18-
Permission is hereby granted, free of charge, to any person obtaining a copy
19-
of this software and associated documentation files (the "Software"), to deal
20-
in the Software without restriction, including without limitation the rights
21-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
22-
copies of the Software, and to permit persons to whom the Software is
23-
furnished to do so, subject to the following conditions:
24-
25-
The above copyright notice and this permission notice shall be included in all
26-
copies or substantial portions of the Software.
27-
28-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
29-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
30-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
31-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
32-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
33-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
34-
SOFTWARE.]]>
14+
<![CDATA[// Copyright 2019 celadari. All rights reserved. MIT license.]]>
3515
</parameter>
3616
<parameter name="regex">
3717
<![CDATA[false]]>

‎src/main/scala/com/celadari/jsonlogicscala/serialize/Marshaller.scala‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,23 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize
23

34
import scala.reflect.runtime.{universe => ru}
45
import play.api.libs.json.JsValue
56

67

8+
/**
9+
* Defines interface of class/object defining marshal method.
10+
* This method serializes a specific scala data structure to json format.
11+
*/
712
trait Marshaller {
813

14+
/**
15+
* Serializes a specific scala data structure to json format.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
* @note serialized value of basic types (Int, String, Boolean, ...) are the values themselves, custom defined classes
19+
* are usually serialized to map of (attribute -> value).
20+
*/
921
def marshal(value: Any): JsValue
1022

1123
// scalastyle:off return

‎src/main/scala/com/celadari/jsonlogicscala/serialize/Serializer.scala‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize
23

34
import play.api.libs.json._
@@ -7,14 +8,42 @@ import com.celadari.jsonlogicscala.converters.CollectionConverters.HasMapValues
78
import com.celadari.jsonlogicscala.exceptions.{IllegalInputException, InvalidValueLogicException}
89

910

11+
/**
12+
* Companion object holding implicit serializer.
13+
* Useful to invoke methods using implicit [[com.celadari.jsonlogicscala.serialize.Serializer]] that do not require
14+
* custom Serializer.
15+
*/
1016
object Serializer {
1117
implicit val defaultSerializer: Serializer = new Serializer()
1218
}
1319

20+
/**
21+
* Responsible for serializing scala data structure [[com.celadari.jsonlogicscala.tree.JsonLogicCore]] to json.
22+
* May be extended to fit custom use cases. Providing the right configuration via
23+
* [[com.celadari.jsonlogicscala.serialize.SerializerConf]] is enough to cover most cases.
24+
* You may redefine methods to handle extreme uncommon cases.
25+
* @param conf: informs of mappings (type_codename -> marshaller).
26+
*/
1427
class Serializer(implicit val conf: SerializerConf) {
28+
/**
29+
* Maps type_codename to [[com.celadari.jsonlogicscala.serialize.Marshaller]].
30+
* @note More specifically, keys should be type_codename of [[com.celadari.jsonlogicscala.tree.types.SimpleTypeValue]]
31+
* as generic types (OptionTypeValue, MapTypeValue, ArrayTypeValue) are handled recursively by getMarshaller.
32+
*/
1533
protected[this] val marshallers: Map[String, Marshaller] = if (conf.isPriorityToManualAdd) conf.marshallerMetaInfAdd ++ conf.marshallersManualAdd
1634
else conf.marshallersManualAdd ++ conf.marshallerMetaInfAdd
1735

36+
/**
37+
* Returns [[com.celadari.jsonlogicscala.serialize.Marshaller]] associated with input typeValue.
38+
* If input typeValue is [[com.celadari.jsonlogicscala.tree.types.SimpleTypeValue]] then returns mapped value
39+
* by marshallers attribute.
40+
* If input typeValue is [[com.celadari.jsonlogicscala.tree.types.OptionTypeValue]],
41+
* [[com.celadari.jsonlogicscala.tree.types.ArrayTypeValue]], [[com.celadari.jsonlogicscala.tree.types.MapTypeValue]]
42+
* then a new [[com.celadari.jsonlogicscala.serialize.Marshaller]] is recursively created by checking paramType of
43+
* input typeValue.
44+
* @param typeValue: input type to return associated Marshaller.
45+
* @return Marshaller associated to typeValue.
46+
*/
1847
protected[this] def getMarshaller(typeValue: TypeValue): Marshaller = {
1948
typeValue match {
2049
case SimpleTypeValue(codename) => marshallers.getOrElse(codename, throw new IllegalInputException(s"No marshaller defined for $codename"))
@@ -65,6 +94,12 @@ class Serializer(implicit val conf: SerializerConf) {
6594
}
6695
}
6796

97+
/**
98+
* Returns tuple of serialized (logic, data) of scala data structure [[com.celadari.jsonlogicscala.tree.ValueLogic]].
99+
* Json-logic-typed format requires logic and data to split.
100+
* @param valueLogic: input ValueLogic to be split into (logic JsValue, data JsValue).
101+
* @return (logic JsValue, data JsValue)
102+
*/
68103
// scalastyle:off return
69104
protected[this] def serializeValueLogic(valueLogic: ValueLogic[_]): (JsValue, JsValue) = {
70105

@@ -84,6 +119,12 @@ class Serializer(implicit val conf: SerializerConf) {
84119
(JsObject(Map("var" -> JsString(varPath), "type" -> jsType)), JsObject(Map(varPath -> jsonLogicDatum)))
85120
}
86121

122+
/**
123+
* Returns tuple of serialized (logic, data) of scala data structure [[com.celadari.jsonlogicscala.tree.ComposeLogic]].
124+
* Json-logic-typed format requires logic and data to split.
125+
* @param composeLogic: input ComposeLogic to be split into (logic JsValue, data JsValue).
126+
* @return (logic JsValue, data JsValue)
127+
*/
87128
protected[this] def serializeComposeLogic(composeLogic: ComposeLogic): (JsValue, JsObject) = {
88129
// retrieve compose logic attributes
89130
val operator = composeLogic.operator
@@ -94,13 +135,24 @@ class Serializer(implicit val conf: SerializerConf) {
94135
(JsObject(Map(operator -> jsonLogic)), jsonLogicData)
95136
}
96137

138+
/**
139+
* Returns tuple of serialized (logic, data) of scala data structure [[Array[com.celadari.jsonlogicscala.tree.JsonLogicCore]]].
140+
* Logic is returned in an array of JsValue and data by merging data JsObject of each condition.
141+
* @param conditions: array of [[com.celadari.jsonlogicscala.tree.JsonLogicCore]].
142+
* @return tuple of split (logic JsValue, data JsObject) from conditions.
143+
*/
97144
protected[this] def serializeArrayOfConditions(conditions: Array[JsonLogicCore]): (JsValue, JsObject) = {
98145
val (jsonLogics, jsonLogicData) = conditions.map(jsonLogic => serialize(jsonLogic)).unzip
99146
(JsArray(jsonLogics), jsonLogicData.map(_.as[JsObject]).reduce(_ ++ _))
100147
}
101148

149+
/**
150+
* Returns tuple of serialized (logic, data) of scala data structure [[com.celadari.jsonlogicscala.tree.JsonLogicCore]].
151+
* Json-logic-typed format requires logic and data to split.
152+
* @param jsonLogic: input JsonLogicCore to be split into (logic JsValue, data JsValue).
153+
* @return (logic JsValue, data JsValue)
154+
*/
102155
def serialize(jsonLogic: JsonLogicCore): (JsValue, JsValue) = {
103-
// if operator is data access
104156
jsonLogic match {
105157
case valueLogic: ValueLogic[_] => serializeValueLogic(valueLogic)
106158
case composeLogic: ComposeLogic => serializeComposeLogic(composeLogic)

‎src/main/scala/com/celadari/jsonlogicscala/serialize/SerializerConf.scala‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize
23

34
import org.apache.xbean.finder.ResourceFinder
@@ -7,7 +8,14 @@ import com.celadari.jsonlogicscala.serialize.defaults._
78
import com.celadari.jsonlogicscala.converters.CollectionConverters.MapHasAsScala
89

910

11+
/**
12+
* Companion object to hold implicit: [[com.celadari.jsonlogicscala.serialize.SerializerConf]], mapping of default
13+
* marshallers (type_codename -> Marshaller), method to create a custom configuration.
14+
*/
1015
object SerializerConf {
16+
/**
17+
* Maps default type_codenames to default marshallers.
18+
*/
1119
val DEFAULT_MARSHALLERS = Map(
1220
BOOL_CODENAME -> MarshallerBoolean,
1321
DOUBLE_CODENAME -> MarshallerDouble,
@@ -20,6 +28,13 @@ object SerializerConf {
2028
NULL_CODENAME -> MarshallerNull
2129
)
2230

31+
/**
32+
* Returns a custom serializer configuration.
33+
* @param path: folder to provider-configuration files.
34+
* @param marshallersManualAdd: map of (type_codename -> Mashaller) to be added to the serializer configuration.
35+
* @param isPriorityToManualAdd: boolean indicating if marshallers manually added have priority over those fetched from provider-configuration folder.
36+
* @return custom serializer configuration.
37+
*/
2338
def createConf(
2439
path: String = "META-INF/services/",
2540
marshallersManualAdd: Map[String, Marshaller] = DEFAULT_MARSHALLERS,
@@ -34,6 +49,13 @@ object SerializerConf {
3449
implicit val serializerConf: SerializerConf = createConf()
3550
}
3651

52+
/**
53+
* Represents a serializer's configuration.
54+
* It informs the serializer how to map a type_codename to a [[com.celadari.jsonlogicscala.serialize.Marshaller]].
55+
* @param marshallerMetaInfAdd: map of (type_codename -> Marshaller) fetched from META-INF resources folder.
56+
* @param marshallersManualAdd: map of (type_codename -> Marshaller) manually added to the configuration.
57+
* @param isPriorityToManualAdd: boolean indicating if marshallers manually added have priority over those fetched from META-INF folder.
58+
*/
3759
case class SerializerConf(
3860
marshallerMetaInfAdd: Map[String, Marshaller],
3961
marshallersManualAdd: Map[String, Marshaller],

‎src/main/scala/com/celadari/jsonlogicscala/serialize/defaults/MarshallerBoolean.scala‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize.defaults
23

34
import play.api.libs.json.{JsBoolean, JsValue}
45
import com.celadari.jsonlogicscala.exceptions.IllegalInputException
56
import com.celadari.jsonlogicscala.serialize.Marshaller
6-
import com.celadari.jsonlogicscala.tree.types.DefaultTypes.BOOL_CODENAME
77

88

9+
/**
10+
* Default marshaller that converts scala boolean value to json format boolean value.
11+
*/
912
object MarshallerBoolean extends Marshaller {
10-
val typeCodename: String = BOOL_CODENAME
11-
val typeClassName: String = classOf[java.lang.Boolean].getName
1213

14+
/**
15+
* Converts a scala boolean value to a json boolean value.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
*/
1319
def marshal(value: Any): JsValue = {
1420
value match {
1521
case boolean: Boolean => JsBoolean(boolean)

‎src/main/scala/com/celadari/jsonlogicscala/serialize/defaults/MarshallerByte.scala‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize.defaults
23

34
import play.api.libs.json.{JsNumber, JsValue}
45
import com.celadari.jsonlogicscala.exceptions.IllegalInputException
56
import com.celadari.jsonlogicscala.serialize.Marshaller
6-
import com.celadari.jsonlogicscala.tree.types.DefaultTypes.BYTE_CODENAME
77

88

9+
/**
10+
* Default marshaller that converts scala byte value to json format number value.
11+
*/
912
object MarshallerByte extends Marshaller {
10-
val typeCodename: String = BYTE_CODENAME
11-
val typeClassName: String = classOf[java.lang.Byte].getName
1213

14+
/**
15+
* Converts a scala byte value to a json number value.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
*/
1319
def marshal(value: Any): JsValue = {
1420
value match {
1521
case byte: Byte => JsNumber(byte)

‎src/main/scala/com/celadari/jsonlogicscala/serialize/defaults/MarshallerDouble.scala‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize.defaults
23

34
import play.api.libs.json.{JsNumber, JsValue}
45
import com.celadari.jsonlogicscala.exceptions.IllegalInputException
56
import com.celadari.jsonlogicscala.serialize.Marshaller
6-
import com.celadari.jsonlogicscala.tree.types.DefaultTypes.DOUBLE_CODENAME
77

88

9+
/**
10+
* Default marshaller that converts scala double value to json format number value.
11+
*/
912
object MarshallerDouble extends Marshaller {
10-
val typeCodename: String = DOUBLE_CODENAME
11-
val typeClassName: String = classOf[java.lang.Double].getName
1213

14+
/**
15+
* Converts a scala double value to a json double value.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
*/
1319
def marshal(value: Any): JsValue = {
1420
value match {
1521
case doubleValue: Double => JsNumber(doubleValue)

‎src/main/scala/com/celadari/jsonlogicscala/serialize/defaults/MarshallerFloat.scala‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize.defaults
23

34
import play.api.libs.json.{JsNumber, JsValue}
45
import com.celadari.jsonlogicscala.exceptions.IllegalInputException
56
import com.celadari.jsonlogicscala.serialize.Marshaller
6-
import com.celadari.jsonlogicscala.tree.types.DefaultTypes.FLOAT_CODENAME
77

88

9+
/**
10+
* Default marshaller that converts scala float value to json format number value.
11+
*/
912
object MarshallerFloat extends Marshaller {
10-
val typeCodename: String = FLOAT_CODENAME
11-
val typeClassName: String = classOf[java.lang.Double].getName
1213

14+
/**
15+
* Converts a scala float value to a json number value.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
*/
1319
def marshal(value: Any): JsValue = {
1420
value match {
1521
case floatValue: Float => JsNumber(floatValue)

‎src/main/scala/com/celadari/jsonlogicscala/serialize/defaults/MarshallerInt.scala‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1+
// Copyright 2019 celadari. All rights reserved. MIT license.
12
package com.celadari.jsonlogicscala.serialize.defaults
23

34
import play.api.libs.json.{JsNumber, JsValue}
45
import com.celadari.jsonlogicscala.exceptions.IllegalInputException
56
import com.celadari.jsonlogicscala.serialize.Marshaller
6-
import com.celadari.jsonlogicscala.tree.types.DefaultTypes.INT_CODENAME
77

88

9+
/**
10+
* Default marshaller that converts scala int value to json format number value.
11+
*/
912
object MarshallerInt extends Marshaller {
10-
val typeCodename: String = INT_CODENAME
11-
val typeClassName: String = classOf[java.lang.Integer].getName
1213

14+
/**
15+
* Converts a scala int value to a json number value.
16+
* @param value: value to be serialized in json format.
17+
* @return serialized value.
18+
*/
1319
def marshal(value: Any): JsValue = {
1420
value match {
1521
case intValue: Int => JsNumber(intValue)

0 commit comments

Comments
 (0)