com.github.rschmitt.dynamicobject

Interface DynamicObject<D extends DynamicObject<D>>

All Superinterfaces:

Map

public interface DynamicObject<D extends DynamicObject<D>>
extends Map

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Modifier and Type	Method and Description
D	afterDeserialization() Deprecated. This method is experimental.
static org.fressian.FressianReader	createFressianReader(InputStream is, boolean validateChecksum) Create a FressianReader instance to read from is.
static org.fressian.FressianWriter	createFressianWriter(OutputStream os) Create a FressianWriter instance to write to os.
static <D extends DynamicObject<D>> void	deregisterTag(Class<D> type) Deregister the reader tag for the given DynamicObject type.
static <T> void	deregisterType(Class<T> type) Deregister the given translator.
static <T> T	deserialize(String edn, Class<T> type) Deserializes a DynamicObject or registered type from a String.
static <T> Stream<T>	deserializeFressianStream(InputStream is, Class<T> type) Lazily deserialize a stream of Fressian-encoded values as the given type.
static <T> Stream<T>	deserializeStream(PushbackReader streamReader, Class<T> type) Lazily deserialize a stream of top-level Edn elements as the given type.
static <T> T	fromFressianByteArray(byte[] bytes) Deserialize and return the Fressian-encoded object in bytes.
Map	getMap()
Class<D>	getType()
D	intersect(D other) Recursively compares this instance with other, returning a new instance containing all of the common elements of both this and other.
D	merge(D other) Return a copy of this instance with other's fields merged in (nulls don't count).
static <D extends DynamicObject<D>> D	newInstance(Class<D> type) Create a "blank" instance of type, backed by an empty Clojure map.
void	prettyPrint() Invokes clojure.pprint/pprint, which writes a pretty-printed representation of the object to the currently bound value of *out*, which defaults to System.out (stdout).
static <D extends DynamicObject<D>> void	registerTag(Class<D> type, String tag) Register a reader tag for a DynamicObject type.
static <T> void	registerType(Class<T> type, EdnTranslator<T> translator) Register an EdnTranslator to enable instances of type to be serialized to and deserialized from Edn using reader tags.
static void	registerType(Class type, String tag, org.fressian.handlers.ReadHandler readHandler, org.fressian.handlers.WriteHandler writeHandler) Register a ReadHandler and WriteHandler to enable instances of type to be serialized to and deserialized from Fressian data.
static String	serialize(Object o) Serialize the given object to Edn.
static void	serialize(Object o, Writer w)
static <T> void	setDefaultReader(BiFunction<String,Object,T> reader) Specify a default reader, which is a function that will be called when any unknown reader tags are encountered.
D	subtract(D other) Recursively compares this instance with other, similar to intersect(D), but returning the fields that are unique to this.
String	toFormattedString() Like prettyPrint(), but returns the pretty-printed string instead of writing it to *out*.
static byte[]	toFressianByteArray(Object o) Serialize a single object o to binary Fressian data.
D	validate() Validate that all fields annotated with @Required are non-null, and that all present fields are of the correct type.
static <D extends DynamicObject<D>> D	wrap(Map map, Class<D> type) Use the supplied map to back an instance of type.

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Method Detail

getMap

Map getMap()

Returns:

the underlying Clojure map backing this instance. Downcasting the return value of this method to any particular Java type (e.g. IPersistentMap) is not guaranteed to work with future versions of Clojure.

getType

Class<D> getType()

Returns:

the apparent type of this instance. Note that getClass will return the class of the interface proxy and not the interface itself.

prettyPrint

void prettyPrint()

Invokes clojure.pprint/pprint, which writes a pretty-printed representation of the object to the currently bound value of *out*, which defaults to System.out (stdout).

toFormattedString

String toFormattedString()

Like prettyPrint(), but returns the pretty-printed string instead of writing it to *out*.

merge

D merge(D other)

Return a copy of this instance with other's fields merged in (nulls don't count). If a given field is present in both instances, the fields in other will take precedence.

Equivalent to: (merge-with (fn [a b] (if (nil? b) a b)) this other)

intersect

D intersect(D other)

Recursively compares this instance with other, returning a new instance containing all of the common elements of both this and other. Maps and lists are compared recursively; everything else, including sets, strings, and POJOs, is treated atomically.

Equivalent to: (nth (clojure.data/diff this other) 2)

subtract

D subtract(D other)

Recursively compares this instance with other, similar to intersect(D), but returning the fields that are unique to this. Uses the same recursion strategy as intersect.

Equivalent to: (nth (clojure.data/diff this other) 0)

validate

D validate()

Validate that all fields annotated with @Required are non-null, and that all present fields are of the correct type. Returns the validated instance unchanged, which allows the validate method to be called at the end of a fluent builder chain.

afterDeserialization

@Deprecated
D afterDeserialization()

Deprecated. This method is experimental.

Post-deserialization hook. The intended use of this method is to facilitate format upgrades. For example, if a new field has been added to a DynamicObject schema, this method can be implemented to add that field (with some appropriate default value) to older data upon deserialization.

If not implemented, this method does nothing.

serialize

static String serialize(Object o)

Serialize the given object to Edn. Any EdnTranslators that have been registered through registerType(java.lang.Class<T>, com.github.rschmitt.dynamicobject.EdnTranslator<T>) will be invoked as needed.

serialize

static void serialize(Object o,
                      Writer w)

deserialize

static <T> T deserialize(String edn,
                         Class<T> type)

Deserializes a DynamicObject or registered type from a String.

Parameters:

edn - The Edn representation of the object.

type - The type of class to deserialize. Must be an interface that extends DynamicObject.

deserializeStream

static <T> Stream<T> deserializeStream(PushbackReader streamReader,
                                       Class<T> type)

Lazily deserialize a stream of top-level Edn elements as the given type.

toFressianByteArray

static byte[] toFressianByteArray(Object o)

Serialize a single object o to binary Fressian data.

fromFressianByteArray

static <T> T fromFressianByteArray(byte[] bytes)

Deserialize and return the Fressian-encoded object in bytes.

createFressianReader

static org.fressian.FressianReader createFressianReader(InputStream is,
                                                        boolean validateChecksum)

Create a FressianReader instance to read from is. The reader will be created with support for all the basic Java and Clojure types, all DynamicObject types registered by calling registerTag(Class, String), and any other types registered by calling registerType(Class, String, ReadHandler, WriteHandler). If validateChecksum is true, the data will be checksummed as it is read; this checksum can later be compared to the expected checksum in the Fressian footer by calling FressianReader.validateFooter().

createFressianWriter

static org.fressian.FressianWriter createFressianWriter(OutputStream os)

Create a FressianWriter instance to write to os. The writer will be created with support for all the basic Java and Clojure types, all DynamicObject types registered by calling registerTag(Class, String), and any other types registered by calling registerType(Class, String, ReadHandler, WriteHandler). If desired, a Fressian footer (containing an Adler32 checksum of all data written) can be written by calling FressianWriter.writeFooter().

deserializeFressianStream

static <T> Stream<T> deserializeFressianStream(InputStream is,
                                               Class<T> type)

Lazily deserialize a stream of Fressian-encoded values as the given type. A Fressian footer, if encountered, will be validated.

wrap

static <D extends DynamicObject<D>> D wrap(Map map,
                                           Class<D> type)

Use the supplied map to back an instance of type.

newInstance

static <D extends DynamicObject<D>> D newInstance(Class<D> type)

Create a "blank" instance of type, backed by an empty Clojure map. All fields will be null.

registerType

static <T> void registerType(Class<T> type,
                             EdnTranslator<T> translator)

Register an EdnTranslator to enable instances of type to be serialized to and deserialized from Edn using reader tags.

registerType

static void registerType(Class type,
                         String tag,
                         org.fressian.handlers.ReadHandler readHandler,
                         org.fressian.handlers.WriteHandler writeHandler)

Register a ReadHandler and WriteHandler to enable instances of type to be serialized to and deserialized from Fressian data.

deregisterType

static <T> void deregisterType(Class<T> type)

Deregister the given translator. After this method is invoked, it will no longer be possible to read or write instances of type unless another translator is registered.

registerTag

static <D extends DynamicObject<D>> void registerTag(Class<D> type,
                                                     String tag)

Register a reader tag for a DynamicObject type. This is useful for reading Edn representations of Clojure records.

deregisterTag

static <D extends DynamicObject<D>> void deregisterTag(Class<D> type)

Deregister the reader tag for the given DynamicObject type.

setDefaultReader

static <T> void setDefaultReader(BiFunction<String,Object,T> reader)

Specify a default reader, which is a function that will be called when any unknown reader tags are encountered. The function will be passed the reader tag (as a string) and the tagged Edn element, and can return whatever it wants.

DynamicObject comes with a built-in default reader for unknown elements, which returns an instance of Unknown, which simply captures the (tag, element) tuple from the Edn reader. The Unknown class is handled specially during serialization so that unknown elements can be serialized correctly; this allows unknown types to be passed through transparently.

To disable the default reader, call DynamicObject.setDefaultReader(null). This will cause the reader to throw an exception if unknown reader tags are encountered.