When applied on raw method, specifies that this raw method may be matched by many, arbitrarily named real methods.
In order to distinguish between real methods when translating raw call into real call,
multi raw method must take real method's RPC name (a String) as one of its parameters
(see methodName).
By default, result type of multi raw method is encoded and the macro engine searches for
appropriate AsRaw or AsReal conversion between real method result type and raw method result type.
When applied on raw parameter, specifies that this raw parameter may be matched by arbitrary number of real
parameters whose values are typically encoded and collected into
(or extracted from) raw parameter value.
The way real parameter values are collected and extracted depends on the type of raw parameter which must be
either:
- an Iterable[R] or any subtype (e.g. List[R])
- a PartialFunction[String,R] or any subtype (e.g. Map[String,R])
R denotes the type used to represent each real parameter value. Be default (unless
verbatim is used) it means
that each real value will be encoded as R and decoded from R - see encoded
for more information about how parameters are encoded and decoded.
If raw parameter is a Coll <: Iterable[Raw] then in order to collect real values into raw value, the macro engine
will search for an instance of CanBuildFrom[Nothing,R,Coll] and use it to build the raw value.
In order to extract real values from raw value, macro generated code will obtain an Iterator[R] from the raw value
and pull and possibly decode all the values. If the iterator is exhausted before all real values could be obtained
then default parameter values specified on real parameters (if any) will be used as fallback values instead of
failing.
If raw parameter is an IndexedSeq[Raw] then extraction is optimized - instead of using an iterator,
values are extracted by index (potentially also falling back to default values of real parameters).
Finally, when raw parameter is a Mapping <: PartialFunction[String,R] then not only values but also parameter
names are collected - the macro engine will search for an instance of CanBuildFrom[Nothing,(String,R),Mapping]
in order to collect the mapping. Parameter names may be adjusted with
rpcName but must be unique in the
scope of a single raw parameter. In order to extract real values from mapping, macro generated code will
call applyOrElse on the raw value giving it the name of each real parameter and also falling back to possible
default parameter values, in case they are missing in the raw call.
Note that when raw parameter is a name-value mapping, you can freely reorder real parameter without fear of
breaking backwards compatibility. You can also safely add new real parameters as long as you provide default
values for them.
Just like single and optional, multi can also be applied on metadata parameters corresponding to
raw methods and raw parameters. The type of multi metadata parameter must be a collection, in the same way
as it's required for multi raw parameters. Metadata classes materialized for raw methods and raw parameters
must extend TypedMetadata[T] where T will be matched against each real method result type or each real
parameter type.
Ultimately, multi may be specified on metadata parameter that reifies annotations from real trait/method/param
(see reifyAnnot). Such metadata parameter must be a collection: any subtype of Iterable[A] where A is the
type of annotation being reified. The macro will then reify all matching annotations from real symbol, including
inherited ones.
When applied on raw method, specifies that this raw method may be matched by many, arbitrarily named real methods. In order to distinguish between real methods when translating raw call into real call, multi raw method must take real method's RPC name (a
String
) as one of its parameters (see methodName). By default, result type of multi raw method is encoded and the macro engine searches for appropriateAsRaw
orAsReal
conversion between real method result type and raw method result type.When applied on raw parameter, specifies that this raw parameter may be matched by arbitrary number of real parameters whose values are typically encoded and collected into (or extracted from) raw parameter value. The way real parameter values are collected and extracted depends on the type of raw parameter which must be either:
- an
Iterable[R]
or any subtype (e.g.List[R]
) - aPartialFunction[String,R]
or any subtype (e.g.Map[String,R]
)R
denotes the type used to represent each real parameter value. Be default (unless verbatim is used) it means that each real value will be encoded asR
and decoded fromR
- see encoded for more information about how parameters are encoded and decoded.If raw parameter is a
Coll <: Iterable[Raw]
then in order to collect real values into raw value, the macro engine will search for an instance ofCanBuildFrom[Nothing,R,Coll]
and use it to build the raw value. In order to extract real values from raw value, macro generated code will obtain anIterator[R]
from the raw value and pull and possibly decode all the values. If the iterator is exhausted before all real values could be obtained then default parameter values specified on real parameters (if any) will be used as fallback values instead of failing.If raw parameter is an
IndexedSeq[Raw]
then extraction is optimized - instead of using an iterator, values are extracted by index (potentially also falling back to default values of real parameters).Finally, when raw parameter is a
Mapping <: PartialFunction[String,R]
then not only values but also parameter names are collected - the macro engine will search for an instance ofCanBuildFrom[Nothing,(String,R),Mapping]
in order to collect the mapping. Parameter names may be adjusted with rpcName but must be unique in the scope of a single raw parameter. In order to extract real values from mapping, macro generated code will callapplyOrElse
on the raw value giving it the name of each real parameter and also falling back to possible default parameter values, in case they are missing in the raw call.Note that when raw parameter is a name-value mapping, you can freely reorder real parameter without fear of breaking backwards compatibility. You can also safely add new real parameters as long as you provide default values for them.
Just like single and optional, multi can also be applied on metadata parameters corresponding to raw methods and raw parameters. The type of multi metadata parameter must be a collection, in the same way as it's required for multi raw parameters. Metadata classes materialized for raw methods and raw parameters must extend
TypedMetadata[T]
whereT
will be matched against each real method result type or each real parameter type.Ultimately, multi may be specified on metadata parameter that reifies annotations from real trait/method/param (see reifyAnnot). Such metadata parameter must be a collection: any subtype of
Iterable[A]
whereA
is the type of annotation being reified. The macro will then reify all matching annotations from real symbol, including inherited ones.