jackdaw.serdes.avro
DEPRECATION NOTICE:
This namespace is deprecated and will soon be removed. Please use
jackdaw.serdes.avro.confluent.
Generating Serdes mapping Clojure <-> Avro.
The intentional API of this NS has three main features -
`SchemaCoercion`, the intentional type registry (of which
`#'+base-schema-type-registry+` is an example) and
`#'avro-serde`.
`avro-serde` is the primary entry point to this namespace for
users. It's a function of a schema-registry configuration, a schema
type registry, and a serde configuration to be instantiated.
The intent is that an end user will `partial` the `avro-serde`
function with their schema registry details and desired type
registry, and use the `partial`'d function as en entry in a registry
as used by `jackdaw.serdes/serde`.
This allows `serdes` and `avro-serde` to be agnostic to application
or environment specific configuration details.
But what's this type registry?
Apache Avro "logical types" - a tool for annotating fields in an
avro record as having some complex interpretation beyond their
serialized format. The `type-registry` for the purposes of the
`avro-serde` function a mapping of addresses to functions which will
when invoked build and return a `SchemaCoercion` instance.
When a Serde is instantiated, a stack of `SchemaCoercion` coersion
helpers is built which will - given a simply deserialized Avro
record - walk its tree coercing its to Clojure types as defined by
the `SchemaCoercion` helpers.
The `SchemaCoercion` stack is built by statically inspecting the parsed
Avro schema, and using the type (if any) and potentially logical
type to select a handler in the `type-registry` which will, given a
function with which to recurse and the schema of that node, build
and return a `SchemaCoercion` handler.
This registry pattern is deliberately chosen so that Avro coercion
will be customizable by the user. As an example, the
`+UUID-type-registry+` is included, which defines a mapping from two
different logical UUID refinements of the binary string type to an
appropriate handler.
A user who wanted to opt into these handlers could simply call
`avro-serde` with
`(merge +base-schema-type-registry+ +UUID-type-registry+)`
Users are HIGHLY encouraged to use the `+base-schema-type-registry+`
as the base for their type registries, as it defines sane handlings
for all of Avro's fundamental types and most of its compounds.
+base-schema-type-registry+
Provides handlers for all of Avro's fundamental types besides `fixed`.
Fixed is unsupported.
+UUID-type-registry+
A type constructor registry.
Provides the logical types `uuid` and `jackdaw.serdes.avro.UUID` coded as strings with coercion
to round-trip `java.util.UUID` instances.
avro-bytes?
Returns true if the object is compatible with Avro bytes, false otherwise
* byte[] - Valid only as a top level schema type
* java.nio.ByteBuffer - Valid only as a nested type
class-name
(class-name x)
Returns a human readable description of x's type
int-castable?
(int-castable? x)
make-coercion-stack
(make-coercion-stack type-registry)
Given a registry mapping Avro type specs to 2-arity coercion
constructors, recursively build up a coercion stack which will go
clj <-> avro, returning the root coercion object.
(satisfies `SchemaCoercion`)
SchemaCoercion
protocol
members
avro->clj
(avro->clj schema-type avro-data)
clj->avro
(clj->avro schema-type clj-data path)
match-avro?
(match-avro? schema-type avro-data)
match-clj?
(match-clj? schema-type clj-data)
serde
(serde type-registry {:keys [avro.schema-registry/client avro.schema-registry/url], :as registry-config} {:keys [avro/schema avro/coercion-cache key?], :as topic-config})
Given a type and logical type registry, a schema registry config with
either a client or a URL and an Avro topic descriptor, build and
return a Serde instance.
serialization-error-msg
(serialization-error-msg x expected-type)
single-float?
(single-float? x)
validate-clj!
(validate-clj! this x path expected-type)