Cask code analysis for data marshalling. It covers the general data mechanism and the JSON data marshalling. Use def scalacOptions = Seq("-Xprint:typer") to see the implicit converters being applied.
1 The General Response.Data
The Data is defined inside the object Response, it is a path-dependent type. An entry point’s result is converted into an HTTP endpoint’s Response.Raw using the convertToResultType method. The method takes an implicit parameter: implicit f: Conversion[T, InnerReturned]).
|
|
Therefore, it looks for an implicit f: T => V. Usually the target type V should provide one implicit converter. For an HTTP endpint that has an InnerReturned of String, the expanded call becomes:
|
|
Four levels of implicit parameters involvled in this call, the create itself is an implict method.
If you define a convertToResultType method in a custom endpoint and calls Response(data), it uses one of the three implicit classes defined in Response.Data object: WritableData[T], NumericData[T: Numeric] and BooleanData(s: Boolean). There are two levels of implicit parameters.
|
|
The WritableData[T] has an implicit parameter implicit f: T => geny.Writable. The geny.Readable defines three implict classes: StringReadable(s: String), ByteArrayReadable(a: Array[Byte]) and class InputStreamReadable(i: InputStream) that convert String, Array[Byte] and InputStream into a Readable, which is a subtype of Writable.
2 postJson
The postJson extends HttpEndpoint[Response[JsonData], ujson.Value]. From input to output, it has three steps:
- read the input to
Map[String, ujson.Value] - convert
ujson.Valueto parameter types of its entry point method - convert entry point’s result into
Response[JsonData]
For a custom type, just declare a serializer and cask and upickle will handle the marshalling :
|
|
2.1 The Input Type
Its Input type is ujson.Value. During its wrapFunction, it
- coverts the request
Request#exchange.getInputStreamintoByteArrayOutputtream - then into
ujson.Value - then
Map[String, uJson.Value]- it is theparamst to entry point in thewrapFunctionmethod:delegate(params).
You don’t need to do anything here. If it failed, it terminates the request and resonse with a 400->BadRequest error.
2.2 ArgSig
The next step is to convert an ujson.Value to a parameter type of the entry point method. For each parameter of the entry point method, the cask macros creates an ArgSig instance. For example, the following code:
|
|
has the following ArgSig:
|
|
The getParamParser uses an implicit parmeter of type InputParser[T] that is defined as JsReader[T] in the postJson end point class. The JsReader object derfines two implicit instances:
defaultJsReader[T]: convertujson.ValuetoT. Requires an implicitupickle.defualt.Readerinstance in scope.ujson.Valueis a subtype ofReader.paramReader: convert values from the request url or body toT, for all non-ujson.Valuetypes.
The implicit parameter for value1 is endpoints.this.JsReader.defaultJsReader[ujson.Value](upickle.this.default.JsValueR)). For value2, it is endpoints.this.JsReader.defaultJsReader[Seq[Int]](upickle.this.default.SeqLikeReader[Seq, Int](upickle.this.default.IntReader, immutable.this.Seq.iterableFactory[Int])).
The implicitly[upickle.default.Reader[T]] matches default.JsValueR and default.SeqLikeReader[Seq, Int].
If cask fails to convert parameter type, it returns Result.Error.InvalidArguments(Seq[ParamError]). The ParamError could be DefaultFailed or Invalid – both result in a 400 error.
2.3 Response[JsonData]
For return data, the call is
|
|
Therefore for JSON data, It uses