simple-avro

Clojure wrapper for Avro schema and serialization.

Changelog

0.0.7

added exception handling for packing data to union fields
some performance optimisations
added Syncable protocol to flush data on demand

0.0.6

BREAKING CHANGES: By default keywords will be used when deserialising maps, records, and the like. Effectively, anything that is turned from an avro-type into a clojure map-type will use keywords as keys. This may break current implementations which rely upon string keys.
Updated to work with Avro 1.7.2.

0.0.5

Forked from asmyczek by Roxxi since original appeared to be abandon.

Quick Start

Schema definition

(defavro-enum State
  "AL" "AK" "AS" "AZ" "AR" "CA" "CO" ; ...
  )

(defavro-record Address
  :street  avro-string
  :city    avro-string
  :state   State
  :zip     avro-int
  :country avro-string)

(defavro-record Contact
  :first   avro-string
  :last    avro-string
  :address Address
  :email   avro-string
  :phone   (avro-union avro-string avro-null))

simple-avro implements all types defined in Avro schema specification. Just prepend avro- to the type name or use plain string names. defavro- macros defined for all named types (defavro-record, defavro-enum and defavro-fixed) create var objects convenient for hierarchical schema compositions. Parameters namespace, aliases and doc can by provided in an optional argument map. In recursive type definitions use string names for type references, for example:

(defavro-record IntList
  :value avro-int 
  :next  (avro-union "IntList" avro-null))

Data serialization

(def contact {:first "Mike" :last "Smith" ...})
(def packed (pack Contact contact <optional encoder>))
(assert (= contact (unpack Contact packed)))

pack serializes objects into generic Avro objects. For json or binary serialization provide an optional json-encoder or binary-encoder.

unpack deserializes Avro objects into clojure primitives. unpack takes several optional keyword arguments:

:fields an optional list of fields to deserialize from a record. Use single filed names or path vectors for nested records, for example [:first [:address :city]] will deserialize only the two fields first and city. If no fields provided, the entire record is deserialized.
:decoder analgous to the optional encoder specified in pack, a specified decoder will be used to de-serialize objects.
:str-key if set to true will unpack an object into a Clojure map structure where ever key is a string instead of a keyword. For example, the following assertion is true:

(def contact {"first" "Mike" "last" "Smith" ...}) (def packed (pack Contact contact )) (assert (= contact (unpack Contact packed :use-keywords false)))

Note, that it doesn't matter whether keys are strings or keywords when packing an object. Note: this would be equivalent to the 0.0.5 and prior behaviors.

Custom types API

simple-avro.core supports only basic Avro types. For custom types import simple-avro.api instead of core. To add support for a new custom type first add a schema best matching the type. For example a Date object can be represented as:

(defavro-type avro-date
  :time avro-long)

Second, register mapping functions from the custom object to Avro record and back using pack-avro-instance and unpack-avro-instance:

(pack-avro-instance Date
  (fn [date] 
    (avro-instance avro-date "time" (.getTime date))))
  
(unpack-avro-instance avro-date
  (fn [rec]
    (Date. (rec "time"))))

Now you can use default pack/unpack methods to serialize Date objects:

(unpack avro-date (pack avro-date (Date.)))

simple-avro.api adds serialization support for Date, UUID and an avro-maybe helper for optional values. For more details see examples and unit tests.

Installation

Leiningen

[simple-avro/simple-avro "0.0.7"]

Maven

<dependency>
  <groupId>simple-avro</groupId>
  <artifactId>simple-avro</artifactId>
  <version>0.0.5</version>
</dependency>

pershyn / simple-avro