trait AUCodec[AU, T] extends AnyRef

abstract class ApplyUnapplyCodec[T] extends ErrorReportingCodec[T] with OOOFieldsObjectCodec[T]

trait CodecWithKeyCodec[T] extends AnyRef

final class DefaultCaseObjectInput extends ObjectInput

abstract class ErrorReportingCodec[T] extends GenCodec[T]

trait FieldInput extends Input

An Input representing an object field.

An Input representing an object field. The same as Input but also provides field name.

final class FieldValues extends AnyRef

abstract class FlatSealedHierarchyCodec[T] extends SealedHierarchyCodec[T]

trait GadtCodec[C[_]] extends AnyRef

case class GenCaseInfo[T](flags: TypeFlags, sourceName: String, annotName: commons.Opt[name], transparent: Boolean, defaultCase: Boolean) extends GenCodecStructure[T] with Product with Serializable

Annotations: @positioned( point = positioned.here )

trait GenCodec[T] extends AnyRef

Type class for types that can be serialized to Output (format-agnostic "output stream") and deserialized from Input (format-agnostic "input stream").

Type class for types that can be serialized to Output (format-agnostic "output stream") and deserialized from Input (format-agnostic "input stream"). GenCodec is supposed to capture generic structure of serialized objects, without being bound to particular format like JSON. The actual format is determined by implementation of Input and Output.

There are convenient macros for automatic derivation of GenCodec instances (materialize and materializeRecursively). However, GenCodec instances still need to be explicitly declared and won't be derived "automagically".

Annotations: @implicitNotFound( "No GenCodec found for ${T}" )

sealed trait GenCodecStructure[T] extends GenInfo[T]

sealed trait GenInfo[T] extends TypedMetadata[T]

trait GenKeyCodec[T] extends AnyRef

Typeclass which implements two-directional conversion between values of some type and field names used in ObjectOutput.writeField and ObjectInput.nextField (FieldInput.fieldName).

Typeclass which implements two-directional conversion between values of some type and field names used in ObjectOutput.writeField and ObjectInput.nextField (FieldInput.fieldName). Every type which has a natural, unambiguous string representation should have a GenKeyCodec.

Annotations: @implicitNotFound( "No GenKeyCodec found for ${T}" )

trait GenObjectCodec[T] extends GenCodec[T]

Subtype of GenCodec which captures serialization to an "object", i.e.

Subtype of GenCodec which captures serialization to an "object", i.e. through ObjectOutput and ObjectInput.

Annotations: @implicitNotFound( "No GenObjectCodec found for ${T}" )

case class GenParamInfo[T](sourceName: String, annotName: commons.Opt[name], hasWhenAbsent: Boolean, transientDefault: Boolean, outOfOrder: Boolean, flags: ParamFlags) extends GenInfo[T] with Product with Serializable

case class GenRef[-S, +T](fun: (S) ⇒ T, rawRef: RawRef) extends Product with Serializable

case class GenUnionInfo[T](flags: TypeFlags, sourceName: String, annotName: commons.Opt[name], flatten: commons.Opt[flatten]) extends GenCodecStructure[T] with Product with Serializable

Annotations: @positioned( point = positioned.here )

abstract class HasApplyUnapplyCodec[T] extends AnyRef

Like HasGenCodec but materializes an ApplyUnapplyCodec instead of just GenCodec.

abstract class HasApplyUnapplyCodecWithDeps[D, T] extends AnyRef

A version of HasApplyUnapplyCodecWithDeps which injects additional implicits into macro materialization.

A version of HasApplyUnapplyCodecWithDeps which injects additional implicits into macro materialization. Implicits are imported from an object specified with type parameter D. It must be a singleton object type, i.e. SomeObject.type.

abstract class HasGadtCodec[C[_]] extends AnyRef

Like HasPolyGenCodec but does not require GenCodec for the type parameter of type constructor C.

Like HasPolyGenCodec but does not require GenCodec for the type parameter of type constructor C. It also provides a GenCodec for wildcard, i.e. C[_].

abstract class HasGenAndKeyCodec[T] extends AnyRef

Automatically injects both GenCodec and GenKeyCodec.

Automatically injects both GenCodec and GenKeyCodec. The type must be a case class or case class like type that wraps exactly one field for which GenKeyCodec exists.

abstract class HasGenCodec[T] extends AnyRef

Convenience abstract class for companion objects of types that have a GenCodec.

Convenience abstract class for companion objects of types that have a GenCodec. There are many other flavors of this base companion class. For example, if you want to inject additional implicits into GenCodec materialization, you can use HasGenCodecWithDeps, for parameterized data types you can use HasPolyGenCodec, etc.

abstract class HasGenCodecFromAU[AU, T] extends AnyRef

Like HasGenCodec but derives the codec from a separately provided custom object which has appropriate apply and unapply (or unapplySeq) methods implemented.

Like HasGenCodec but derives the codec from a separately provided custom object which has appropriate apply and unapply (or unapplySeq) methods implemented. Materialization is done by GenCodec.fromApplyUnapplyProvider macro. The object containing apply and unapply must be specified with object singleton type passed as type parameter AU.

abstract class HasGenCodecWithDeps[D, T] extends AnyRef

A version of HasGenCodec which injects additional implicits into macro materialization.

A version of HasGenCodec which injects additional implicits into macro materialization. Implicits are imported from an object specified with type parameter D. It must be a singleton object type, i.e. SomeObject.type.

abstract class HasGenObjectCodec[T] extends AnyRef

Like HasGenCodec but materializes a GenObjectCodec instead of just GenCodec.

abstract class HasGenObjectCodecWithDeps[D, T] extends AnyRef

A version of HasGenObjectCodec which injects additional implicits into macro materialization.

A version of HasGenObjectCodec which injects additional implicits into macro materialization. Implicits are imported from an object specified with type parameter D. It must be a singleton object type, i.e. SomeObject.type.

abstract class HasPolyGenCodec[C[_]] extends AnyRef

Like HasGenCodec but for parameterized (generic) data types.

abstract class HasPolyGenCodecWithDeps[D, C[_]] extends AnyRef

A version of HasPolyGenCodec which injects additional implicits into macro materialization.

A version of HasPolyGenCodec which injects additional implicits into macro materialization. Implicits are imported from an object specified with type parameter D. It must be a singleton object type, i.e. SomeObject.type.

abstract class HasPolyGenObjectCodec[C[_]] extends AnyRef

Like HasGenObjectCodec but for parameterized (generic) data types.

abstract class HasPolyGenObjectCodecWithDeps[D, C[_]] extends AnyRef

A version of HasPolyGenObjectCodec which injects additional implicits into macro materialization.

A version of HasPolyGenObjectCodec which injects additional implicits into macro materialization. Implicits are imported from an object specified with type parameter D. It must be a singleton object type, i.e. SomeObject.type.

abstract class HasRecursiveGenCodec[T] extends AnyRef

Like HasGenCodec but uses GenCodec.materializeRecursively for materialization.

trait Input extends Any

Represents an abstract source from which a value may be deserialized (read).

Represents an abstract source from which a value may be deserialized (read). Each of the read methods tries to read a value of specified type and may throw an exception (usually ReadFailure) when reading is not successful.

An Input value should be assumed to be stateful. If any of the readX methods have already been called, the Input instance can no longer be used and MUST be discarded.

In order to ignore the value kept in this Input, skip() MUST be called.

In summary: every Input MUST be fully exhausted by either calling one of the read methods which returns successful value or by calling skip(). Also, ListInput and ObjectInput instances returned from this Input must also be fully exhausted on their own.

trait InputAndSimpleInput extends Input with SimpleInput

trait InputMetadata[T] extends AnyRef

Base trait for metadata markers identifying custom native metadata information that particular Input and Output implementations might want to support.

Base trait for metadata markers identifying custom native metadata information that particular Input and Output implementations might want to support. Example: JsonType

abstract class InputWrapper extends Input

abstract class IntWrapperCompanion[T] extends TransparentWrapperCompanion[Int, T]

trait ListInput extends SequentialInput

Represents an abstract source of sequence of values that can be deserialized.

Represents an abstract source of sequence of values that can be deserialized. ListInput instance is stateful and MUST be read strictly sequentially. This means, you MUST fully exhaust an Input instance returned by nextElement() before calling nextElement() again. For this reason, ListInput is not an Iterator despite having similar interface (Iterator would easily allow e.g. conversion to List[Input] which would be illegal).

ListInput MUST always be fully exhausted. In order to ignore any remaining elements, skipRemaining() may be used.

trait ListOutput extends SequentialOutput

Represents an abstract sink for serialization of sequences of values.

Represents an abstract sink for serialization of sequences of values. Any ListOutput instance must be assumed to be stateful and used in strictly sequential manner. After all elements have been written, finish() must be called to explicitly mark that the list is complete.

abstract class LongWrapperCompanion[T] extends TransparentWrapperCompanion[Long, T]

abstract class NestedSealedHierarchyCodec[T] extends SealedHierarchyCodec[T]

trait ObjectInput extends SequentialInput

Represents an abstract source of key-value mappings that can be deserialized.

Represents an abstract source of key-value mappings that can be deserialized. ObjectInput instance is stateful and MUST be read strictly sequentially. This means, you MUST fully exhaust any Input instance returned by nextField() before calling nextField() again. For this reason, ObjectInput is not an Iterator despite having similar interface (Iterator would easily allow e.g. conversion to List[(String, Input)] which would be illegal).

ObjectInput MUST always be fully exhausted. In order to ignore any remaining key-value mappings, skipRemaining() may be used.

trait ObjectOutput extends SequentialOutput

Represents an abstract sink for serialization of string-to-value mappings.

Represents an abstract sink for serialization of string-to-value mappings. Any ObjectOutput instance must be assumed to be stateful and used in strictly sequential manner. After all key-value pairs have been written, finish() must be called to explicitly mark that the object is complete.

ObjectOutput MUST preserve information about the order in which fields are written. ObjectInput is required to read fields in exactly the same order as ObjectOutput writes them.

trait Output extends Any

Represents an abstract sink to which a value may be serialized (written).

Represents an abstract sink to which a value may be serialized (written). An Output instance should be assumed to be stateful. After calling any of the write methods, it MUST NOT be reused. This means that Output instance can be used only to write a single value. However, if the value to write is complex, one can use writeList/writeSet or writeObject/writeMap.

trait OutputAndSimpleOutput extends Output with SimpleOutput

abstract class OutputWrapper extends Output

final class PeekingObjectInput extends ObjectInput

Wrapper over ObjectInput that lets you peek next field name without advancing the input.

trait PolyCodec[C[_]] extends AnyRef

trait PolyObjectCodec[C[_]] extends AnyRef

abstract class ProductCodec[T <: Product] extends ApplyUnapplyCodec[T]

sealed trait RawRef extends AnyRef

trait RecursiveAutoCodecs extends AnyRef

trait RecursiveCodec[T] extends AnyRef

abstract class SealedHierarchyCodec[T] extends ErrorReportingCodec[T] with ObjectCodec[T]

trait SequentialInput extends Any

trait SequentialOutput extends Any

Base trait for outputs which allow writing of multiple values in sequence, i.e.

Base trait for outputs which allow writing of multiple values in sequence, i.e. ListOutput and ObjectOutput.

final case class SerializationName[T](name: String) extends AnyVal with Product with Serializable

trait SerializationNameLowPrio extends AnyRef

trait SimpleInput extends Any

Represents an abstract source of primitive (or "simple") values.

Represents an abstract source of primitive (or "simple") values. May be obtained from Input.

abstract class SimpleInputWrapper extends SimpleInput

trait SimpleOutput extends Any

Represent an abstract sink for "primitive" values, i.e.

Represent an abstract sink for "primitive" values, i.e. ones that can be written as a whole with a simple method call (as opposed to lists and objects). Simple values must NEVER be null. Output.writeNull must be used instead to handle null values.

abstract class SimpleOutputWrapper extends SimpleOutput

sealed trait SimpleRawRef extends RawRef

class SimpleValueFieldInput extends SimpleValueInput with FieldInput

class SimpleValueInput extends InputAndSimpleInput

An Input for GenCodec complementary to SimpleValueOutput.

class SimpleValueOutput extends OutputAndSimpleOutput

An Output for GenCodec which serializes data into plain Scala objects.

- "lists" are represented as Scala Lists - "objects" are represented as String-keyed Scala Maps - simple values (strings, numbers, booleans, byte arrays) are represented as themselves, unchanged

In other words, serialized value yield by SimpleValueOutput is a Scala object guaranteed to be one of: - null - Int - Long - Double - BigInt - BigDecimal - Boolean - String - Array[Byte] - scala.collection.Seq[Any] where every element is also one of the listed types - scala.collection.Map[String,Any] where every value is also one of the listed types

Such format is often useful as an intermediate representation. For example, it can be later safely passed to standard Java serialization. However, for performance reasons it's recommended to implement dedicated Input and Output for the final format (e.g. binary or JSON).

class SingletonCodec[T <: Singleton] extends ErrorReportingCodec[T] with OOOFieldsObjectCodec[T]

class StreamFieldInput extends StreamInput with FieldInput

class StreamInput extends InputAndSimpleInput

class StreamOutput extends OutputAndSimpleOutput

abstract class StringWrapperCompanion[T] extends TransparentWrapperCompanion[String, T]

abstract class TransparentWrapperCompanion[R, T] extends TransparentWrapping[R, T] with (R) ⇒ T

Base class for companion objects of case classes which are transparent wrappers over their only field.

Base class for companion objects of case classes which are transparent wrappers over their only field. This is the usual way of providing TransparentWrapping for some type and is intended as a replacement for transparent annotation.

trait TransparentWrapping[R, T] extends AnyRef

A typeclass which serves as evidence that some type T is a "transparent" wrapper of some other type.

A typeclass which serves as evidence that some type T is a "transparent" wrapper of some other type. This usually means that instances of various typeclasses (e.g. GenCodec) for type T could be automatically derived from instances for the wrapped type. How this actually happens is decided in each typeclass which can define appropriate implicit.

trait TupleGenCodecs extends AnyRef

trait TypeMarker[T] extends AnyRef

Base trait for type markers identifying custom native types that particular Input and Output implementations might want to support.

class defaultCase extends Annotation with StaticAnnotation

When materializing a GenCodec for sealed hierarchy with @flatten annotation, you can use this annotation on one of case classes or objects to mark it as the default one.

When materializing a GenCodec for sealed hierarchy with @flatten annotation, you can use this annotation on one of case classes or objects to mark it as the default one. If during deserialization the codec is unable to find the _case field and determine the case class/object to deserialize, it will try to deserialize the data to the class/object marked with this annotation.

This is useful for retaining backwards compatibility with serialized format when refactoring code and replacing a simple case class with a sealed hierarchy.

class flatten extends Annotation with StaticAnnotation

Changes the serialization format used by GenCodecs automatically derived for sealed hierarchies.

Changes the serialization format used by GenCodecs automatically derived for sealed hierarchies. The format is changed from "nested" to "flat".

@flatten sealed trait Value
case class Numeric(int: Int) extends Value
case class Textual(string: String) extends Value
object Value {
  implicit val codec: GenCodec[Value] = GenCodec.materialize[Value]
}

Without flatten annotation, the "nested" format is used, e.g. when Numeric(42) would be encoded to JSON as:

{"Numeric": {"int": 42}}

but when flatten annotation is applied on sealed trait/class, then it changes to:

{"_case": "Numeric", "int": 42}

The "_case" field name can be customized with annotation parameter

class generated extends Annotation with StaticAnnotation

May be used on members of objects, case classes or any types having companion object with case class like apply and unapply/unapplySeq methods in order to add additional, generated fields to data serialized by auto-materialized GenCodecs.

case class User(id: Long, login: String) {
  @generated def upperLogin: String = login.toUpperCase
}
object User {
  implicit val codec: GenCodec[User] = GenCodec.materialize[User]
}

This annotation may be applied on vals, vars and defs. When applied on a def, it must be either parameterless (no parameter lists or empty parameter list) or accept only implicit parameters, provided that all the implicit values are available in the scope where GenCodec is materialized (implicit values will be "baked in" the codec).

NOTE: @generated annotation may be defined on any level of inheritance hierarchy - it will be inherited from implemented and overridden members.

class name extends Annotation with StaticAnnotation with NotInheritedFromSealedTypes

Can be used on case class fields and classes in sealed hierarchy to instruct automatically derived GenCodec to use particular name instead of just using parameter or class name.

For example:

sealed trait Base
@name("STH")
case class Something(@name("dbname") paramname: Int) extends Base
object Base {
  implicit codec = GenCodec.auto[Base]
}

GenCodec.write[Base](someOutput, Something(42)) would write an object {"STH": {"dbname": 42}} instead of {"Something": {"paramname": 42}}.

NOTE: @name annotation may be defined on any level of inheritance hierarchy. For instance, if a case class field overrides a method of some base trait, the @name annotation may be used on that method and will affect the case class field.

class outOfOrder extends Annotation with StaticAnnotation

To be used in conjunction with flatten.

To be used in conjunction with flatten. It can be applied on one or more of case class fields in a sealed hierarchy to instruct the auto-materialized GenCodec that this particular field may appear before _case field in the serialized format during reading.

@flatten sealed trait Base
case class FirstCase(@outOfOrder tag: String, int: Int) extends Base
case class SecondCase(dbl: Double) extends Base
object Base {
  implicit val codec: GenCodec[Base] = GenCodec.materialize[Base]
}

The following JSON (assuming this is the representation used) would correctly deserialize as FirstCase("someTag", 42):

{"tag": "someTag", "_case": "FirstCase", "int": 42}

Field annotated with @outOfOrder annotation doesn't have to be present in every case class, but if it is present, all case classes must annotate it and give it exactly the same type. The annotation may also be inherited, e.g.

@flatten sealed trait Base {
  @outOfOrder def tag: String
}
case class FirstCase(tag: String, int: Int) extends Base
case class SecondCase(tag: String, dbl: Double) extends Base

The direct motivation for this annotation was the ability to use flatten on MongoDB entities with an _id field. When reading entities from MongoDB, the _id field is always at the beginning of a BSON document and therefore GenCodec must be able to read it before it knows which case class of sealed hierarchy is being deserialized.

class transientDefault extends Annotation with StaticAnnotation

If some case class field has default value or whenAbsent annotation, you can use transientDefault on this field to instruct an automatically derived GenCodec to not persist the value of that field if it's equal to the default value.

For example:

case class Something(str: String, @transientDefault int: Int = 42)
object Something {
  implicit val codec = GenCodec.auto[Something]
}

GenCodec.write(someOutput, Something("lol", 10)) would yield object {"str": "lol", "int": 10} but GenCodec.write(someOutput, Something("lol", 42)) would yield object {"str": "lol"} because the value of int is the same as the default value.

NOTE: transientDefault also works for method parameters in RPC framework.

class transparent extends Annotation with StaticAnnotation

Can be used on case classes with exactly one field to instruct automatically generated GenCodec that the class is a "transparent wrapper" and should be serialized to the same representation as the value of its sole field.

NOTE: TransparentWrapperCompanion is another and even better way of achieving the same thing. (@transparent annotation will probably become deprecated).

class whenAbsent[+T] extends Annotation with StaticAnnotation

An alternative way to provide default value for case class parameter used during deserialization with GenCodec when its field is missing in data being deserialized.

An alternative way to provide default value for case class parameter used during deserialization with GenCodec when its field is missing in data being deserialized. Normally, Scala-level default parameter values are picked up, but you may want to use this annotation instead if you don't want to pollute your Scala classes with unintended default parameter values (i.e. you want a default value *only* for deserialization).

case class HasDefault(@whenAbsent("default") str: String)
object HasDefault extends HasGenCodec[HasDefault]

If a parameter has both Scala-level default value and is annotated with @whenAbsent then value from annotation takes priority. You can use this to have different source-level default value and different default value for deserialization. You can also leverage this to "remove" default value for deserialization:

case class HasNoDefault(@whenAbsent(throw new Exception) str: String = "default")
object HasDefault extends HasGenCodec[HasDefault]

NOTE: whenAbsent also works for method parameters in RPC framework.

Packages

serialization

package serialization

Type Members

Value Members

Ungrouped