Merge pull request #34 from rallyhealth/reads-recover

Add .recover methods to Reads and fix missing package object for Play 2.7

Author: jeffmay

README.md

@@ -52,8 +52,10 @@ Pretty much all of these tools become available when you `import `[`play.api.lib
 
 ## Implicits
 
-By importing `play.api.libs.json.ops._`, you get access to implicits that provide:
+By importing `play.api.libs.json.ops._`, you get access to:
 
+* `PlayJsonMacros.nullableReads` macro that will read `null` as `[]` for all container fields of a `case class`
+* `Reads`, `Format`, and `OFormat` extension methods to recover from exceptions
 * Many extension methods for the `play.api.libs.json.Json`
   - `Format.of[A]`, `OFormat.of[A]`, and `OWrites.of[A]` for summoning formats the same as `Reads.of[A]` and `Writes.of[A]`
   - `Format.asEither[A, B]` for reading and writing an either value based on some condition
@@ -63,10 +65,64 @@ By importing `play.api.libs.json.ops._`, you get access to implicits that provid
   - In Play 2.3, the `Json.format` and `Json.writes` macros would return `Format` and `Writes` instead of `OFormat` and
     `OWrites`, even though the macros would only produce these types. The play-json-ops for Play 2.3 provides a `Json.oformat`
     and `Json.owrites` which uses the underlying Play Json macros, but it casts the results.
-* `Reads` and `Writes` for tuple types by writing the result as a `JsArray`
+* `Reads` and `Writes` implicits for tuple types (encoded as a `JsArray`)
 * The `JsValue` extension method `.asOrThrow[A]` which throws a better exception that `.as[A]`
 * And handy syntax for the features listed below
 
+## Tolerant Container Reads Macro
+
+Extending the `TolerantContainerFormats` trait or importing from its companion object will give you the ability to call
+`.readNullableContainer` on a `Reads` instance. This will allow you to parse `null` fields as empty collections.
+
+You can also use `PlayJsonMacros.nullableReads` to create a `Reads` for a `case class` that will accept either `null`
+or missing field values for any container fields (`Seq`, `Set`, `Map`, etc) using the same method.
+
+```scala
+case class Example(values: Seq[Int])
+object Example extends TolerantContainerFormats {
+
+  val nonMacroExample: Reads[Seq[Int]] = (__ \ "values").readNullableContainer[Seq, Int]
+  assert(Json.parse("null").as(nonMacroExample) == JsSuccess(Seq()))
+  assert(Json.parse("[]").as[Example] == JsSuccess(Seq()))
+  assert(Json.parse("[1]").as[Example] == JsSuccess(Seq(1)))
+
+  val macroExample: Reads[Example] = PlayJsonMacros.nullableReads[Example]
+  assert(Json.parse("{}").as(macroExample) == JsSuccess(Example(Seq())))
+  assert(Json.parse("""{"values":null}""").as(macroExample) == JsSuccess(Example(Seq())))
+  assert(Json.parse("""{"values":[]}""").as(macroExample) == JsSuccess(Example(Seq())))
+  assert(Json.parse("""{"values":[1]}""").as(macroExample) == JsSuccess(Example(Seq(1))))
+}
+```
+
+## Reads Recovery Methods
+
+You can call `.recoverJsError`, `.recoverTotal`, or `.recoverWith` on a `Reads`, `Format`, or `OFormat` instance.
+These methods allow you to recover from exceptions thrown during the reading process into an appropriate `JsResult`.
+
+```scala
+object ReadsRecoveryExamples {
+
+  // converts all exceptions into a JsError with the exception captured as an argument in the JsonValidationError
+  val readIntAsString = Reads.of[String].map(_.toInt).recoverJsError
+  assert(readIntAsString.reads("not a number").isError) // no exception thrown
+
+  // converts only the matched exceptions to JsResults, all others continue to throw
+  val invertReader = Reads.of[String].map(1 / _.toDouble).recoverWith {
+    case _: ArithmeticException => JsSuccess(Double.MaxValue) 
+  }
+  invertReader.reads("not a number") // throws NumberFormatException
+  assert(invertReader.reads("0") == JsSuccess(Double.MaxValue)) // handles ArithmeticException
+
+  // converts all exceptions into some value of the right type
+  val readAbsValueOrSentinel = Reads.of[String].map(_.toInt.abs).recoverTotal(_ => -1)
+  assert(readAbsValueOrSentinel.reads("not a number") == JsSuccess(-1))
+
+  // these can be combined, of course
+  val safeInvertReader = invertReader.recoverJsError
+  assert(safeInvertReader.reads("not a number").isError) // no exception thrown
+}
+```
+
 ## Automatic Automated Tests
 
 To get free test coverage, just extend `PlayJsonFormatSpec[T]` where `T` is a serializable type that you

build.sbt

@@ -44,7 +44,7 @@ def commonProject(id: String, projectPath: String, scalacVersion: String): Proje
     classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.Flat,
 
     scalacOptions ++= Seq(
-      "-deprecation",
+      "-deprecation:false",
       "-feature",
       "-Xfatal-warnings",
       "-Ywarn-dead-code",
@@ -82,15 +82,7 @@ def playJsonOpsCommon(scalacVersion: String, includePlayVersion: String): Projec
   commonProject(id, projectPath, scalacVersion).settings(
     libraryDependencies ++= Seq(
       playJson(includePlayVersion)
-    ) ++ {
-      // Test-only dependencies
-      includePlayVersion match {
-        case Play_2_7 => Seq(
-          scalaTest(scalaCheckVersion)
-        )
-        case _ => Seq()
-      }
-    }.map(_ % Test)
+    )
   )
 }
 
@@ -117,8 +109,8 @@ def playJsonOps(scalacVersion: String, includePlayVersion: String): Project = {
           scalaCheckOps(scalaCheckVersion),
           scalaTest(scalaCheckVersion)
         ) ++ {
-          includePlayVersion match {
-            case Play_2_7 => Seq(
+          scalaCheckVersion match {
+            case ScalaCheck_1_14 => Seq(
               scalaTestPlusScalaCheck(scalaCheckVersion)
             )
             case _ => Seq()

play-json-ops-common/src/main/scala/play/api/libs/json/ops/FormatOps.scala

@@ -159,7 +159,7 @@ object FormatOps {
       (implicit
         leftType: ClassTag[Left], rightType: ClassTag[Right],
         leftAsX: Left <:< X,      rightAsX: Right <:< X
-        ): Format[X] = {
+      ): Format[X] = {
       from(jsonIsRight, {
         case leftType(_) => false
         case rightType(_) => true
@@ -200,4 +200,3 @@ object FormatOps {
     }
   }
 }
-

play25-json-ops/src/test/scala/play/api/libs/json/ops/JsonImplicitsSpec.scala renamed to play-json-tests-common/src/test/scala/play/api/libs/json/ops/JsonImplicitsSpec.scala

@@ -0,0 +1,111 @@
+package play.api.libs.json.ops
+
+import play.api.data.validation.ValidationError
+import play.api.libs.json._
+
+import scala.language.higherKinds
+import scala.reflect.ClassTag
+import scala.util.control.NonFatal
+
+trait RecoverOps[F[x] <: Reads[x], A] extends Any {
+
+  def unsafeReader: Reads[A]
+
+  /**
+   * Recovers from all exceptions thrown during reading, producing an exception-safe Reads.
+   */
+  def recoverTotal(recoverFn: Throwable => A): Reads[A] = build {
+    Reads { json: JsValue =>
+      try {
+        unsafeReader.reads(json)
+      } catch {
+        case NonFatal(ex) => JsSuccess(recoverFn(ex))
+      }
+    }
+  }
+
+  /**
+   * Translates exceptions thrown during reading into JsError validation results.
+   */
+  def recoverJsError(implicit ct: ClassTag[A]): Reads[A] = {
+    recoverWith {
+      case ex => RecoverOps.expectedTypeError(ct.runtimeClass, ex)
+    }
+  }
+
+  /**
+   * Recovers from some exceptions thrown during reading into a [[JsResult]].
+   *
+   * @note if the recover function is undefined for an exception, the [[Reads]] produced is still unsafe.
+   */
+  def recoverWith(
+    recoverFn: PartialFunction[Throwable, JsResult[A]]
+  ): Reads[A] = build {
+    Reads { json: JsValue =>
+      try {
+        unsafeReader.reads(json)
+      } catch {
+        case NonFatal(ex) if recoverFn isDefinedAt ex => recoverFn(ex)
+      }
+    }
+  }
+
+  // Subclasses need to define how to build an instance of F[A] from a Reads[A]
+  protected def build(safeReader: Reads[A]): F[A]
+}
+
+object RecoverOps {
+
+  /**
+   * Similar to the Class.getSimpleName method, except it does not throw any exceptions and
+   * handles Scala inner classes better.
+   */
+  def safeSimpleClassName(cls: Class[_]): String = {
+    // This logic is designed to be robust without much noise
+    // 1. use getName to avoid runtime exceptions from getSimpleName
+    // 2. filter out '$' anonymous class / method separators
+    // 3. start the full class name from the first upper-cased outer class name
+    //    (to avoid picking up unnecessary package names)
+    cls.getName
+      .split('.')
+      .last // safe because Class names will never be empty in any realistic scenario
+      .split('$')
+      .mkString(".")
+  }
+
+  /**
+   * Following the style of play json's DefaultReads class. Type should be all lowercase.
+   *
+   * @note this method is not cross-compatible between Play 2.5 and above. Once everything
+   *       uses [[JsonValidationError]], we can move this whole file to the common project.
+   *
+   * e.g.
+   * error.expected.string
+   * error.expected.uuid
+   */
+  def expectedTypeError(tpe: String, args: Any*): JsError = {
+    val className = tpe.toLowerCase
+    JsError(ValidationError(s"error.expected.$className", args: _*))
+  }
+
+  /**
+   * Same as [[expectedTypeError]], except safely converts the class to a string.
+   */
+  def expectedTypeError(cls: Class[_], args: Any*): JsError = {
+    expectedTypeError(safeSimpleClassName(cls), args: _*)
+  }
+}
+
+class ReadsRecoverOps[A](override val unsafeReader: Reads[A]) extends AnyVal with RecoverOps[Reads, A] {
+  final override protected def build(safeReader: Reads[A]): Reads[A] = safeReader
+}
+
+class FormatRecoverOps[A](val unsafeFormat: Format[A]) extends AnyVal with RecoverOps[Format, A] {
+  final override def unsafeReader: Reads[A] = unsafeFormat
+  final override protected def build(safeReader: Reads[A]): Format[A] = Format(safeReader, unsafeFormat)
+}
+
+class OFormatRecoverOps[A](val unsafeFormat: OFormat[A]) extends AnyVal with RecoverOps[OFormat, A] {
+  final override def unsafeReader: Reads[A] = unsafeFormat
+  final override protected def build(safeReader: Reads[A]): OFormat[A] = OFormat(safeReader, unsafeFormat)
+}

play25-json-ops/src/main/scala/play/api/libs/json/ops/RecoverOps.scala

@@ -9,10 +9,17 @@ import play.api.libs.json._
  * @note this only applies for [[DateTime]] because [[org.joda.time.LocalDateTime]],
  *       [[java.util.Date]], and [[java.sql.Date]] do not carry along the time zone.
  */
+@deprecated(
+  "A better approach is to explicitly convert time zones in your own code when appropriate and use the timezone " +
+    "passed in the JSON string or fallback on one that is configured for the user.  " +
+    "If no timezone is given in the JSON, the default will be the global DateTimeZone.getDefault (which is mutable).  " +
+    "This is not available for Play >2.5 artifacts since 2.0.0 and will be removed when Play 2.5 support is removed.",
+  "3.1.0"
+)
 trait UTCFormats {
 
   /**
-   * A good default for when you don't care about the [[DateTimeZone]] of the server
+   * For when you don't care about the [[DateTimeZone]] of the server
    * that is parsing the [[DateTime]] and prefer to have all dates and times in
    * Universal Coordinated Time (UTC).
    */

play25-json-ops/src/main/scala/play/api/libs/json/ops/UTCFormats.scala

@@ -1,3 +1,12 @@
 package play.api.libs.json
 
-package object ops extends JsonImplicits
+import scala.language.implicitConversions
+
+package object ops extends JsonImplicits {
+
+  implicit def safeReadsOps[A](reads: Reads[A]): ReadsRecoverOps[A] = new ReadsRecoverOps(reads)
+
+  implicit def safeFormatOps[A](format: Format[A]): FormatRecoverOps[A] = new FormatRecoverOps(format)
+
+  implicit def safeOFormatOps[A](oformat: OFormat[A]): OFormatRecoverOps[A] = new OFormatRecoverOps(oformat)
+}

play25-json-ops/src/main/scala/play/api/libs/json/ops/package.scala

@@ -0,0 +1,38 @@
+package play.api.libs.json.ops
+
+import org.scalatest.FreeSpec
+import org.scalatest.Matchers._
+import play.api.data.validation.ValidationError
+import play.api.libs.json._
+
+class ReadsRecoverOpsSpec extends FreeSpec {
+
+  private val it = classOf[ReadsRecoverOps[_]].getSimpleName
+
+  s"$it.recoverJsError should recover from exceptions with a JsError" in {
+    val readStringAsInt = Reads.of[String].map(_.toInt).recoverJsError
+    readStringAsInt.reads(JsString("not a number")) match {
+      case JsError(Seq((JsPath, Seq(ValidationError(Seq(message), ex))))) =>
+        assertResult("error.expected.int")(message)
+        ex shouldBe a[NumberFormatException]
+      case o => fail(s"Expected a single error message with a single exception, not $o")
+    }
+  }
+
+  s"$it.recoverWith should throw any exception not caught by the partial function" in {
+    val readStringAsIntInverted = Reads.of[String].map(1 / _.toInt).recoverWith {
+      case ex: NumberFormatException => RecoverOps.expectedTypeError(classOf[Int], ex)
+    }
+    // it should catch format exceptions
+    assert(readStringAsIntInverted.reads(JsString("not a number")).isError)
+    // but math exceptions are uncaught
+    an[ArithmeticException] shouldBe thrownBy {
+      readStringAsIntInverted.reads(JsString("0"))
+    }
+  }
+
+  s"$it.recoverTotal should call the recover function" in {
+    val readStringAsIntInverted = Reads.of[String].map(_.toInt.abs).recoverTotal(_ => -1)
+    assertResult(JsSuccess(-1))(readStringAsIntInverted.reads(JsString("not a number")))
+  }
+}

play25-json-ops/src/test/scala/play/api/libs/json/ops/ReadsRecoverOpsSpec.scala

@@ -16,10 +16,12 @@ object UseUTC extends UTCFormats {
 
 class UTCFormatSpec extends WordSpec {
 
+  private[this] val pacificTimeZone = DateTimeZone.forID("US/Pacific")
+
   "Json.format by default" should {
     "deserialize with the current time zone" in {
-      val dt = new DateTime
-      assertResult(dt.getZone) {
+      val dt = new DateTime(pacificTimeZone)
+      assertResult(DateTimeZone.getDefault) {
         val notUTC = Json.toJson(NotUTC(dt)).as[NotUTC]
         notUTC.when.getZone
       }
@@ -29,7 +31,7 @@ class UTCFormatSpec extends WordSpec {
   "UTCFormats" should {
 
     "override the standard Format[DateTime]" in {
-      val dt = new DateTime
+      val dt = new DateTime(pacificTimeZone)
       assertResult(DateTimeZone.UTC) {
         val useUTC = Json.toJson(UseUTC(dt)).as[UseUTC]
         useUTC.when.getZone