com.github.rschmitt.dynamicobject.DynamicObject Maven / Gradle / Ivy

Go to download
package com.github.rschmitt.dynamicobject;

public interface DynamicObject> {
    /**
     * @return 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.
     */
    Object getMap();

    /**
     * @return the apparent type of this instance. Note that {@code getClass} will return the class of the interface
     * proxy and not the interface itself.
     */
    Class getType();

    /**
     * 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).
     */
    void prettyPrint();

    /**
     * Like {@link DynamicObject#prettyPrint}, but returns the pretty-printed string instead of writing it to *out*.
     */
    String toFormattedString();

    /**
     * Return a copy of this instance with {@code other}'s fields merged in (nulls don't count). If a given field is
     * present in both instances, the fields in {@code other} will take precedence.
     * 
     * Equivalent to: {@code (merge-with (fn [a b] (if (nil? b) a b)) this other)}
     */
    T merge(T other);

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

     * Equivalent to: {@code (nth (clojure.data/diff this other) 2)}
     */
    T intersect(T other);

    /**
     * Recursively compares this instance with {@code other}, similar to {@link #intersect}, but returning the fields that
     * are unique to {@code this}. Uses the same recursion strategy as {@code intersect}.
     * 
     * Equivalent to: {@code (nth (clojure.data/diff this other) 0)}
     */
    T subtract(T other);

    /**
     * Validate that all fields annotated with @Required are non-null, and that all present fields are of the correct
     * type.
     */
    void validate();

    /**
     * Serialize the given object to Edn. Any {@code EdnTranslator}s that have been registered through
     * {@link DynamicObject#registerType} will be invoked as needed.
     */
    public static > String serialize(T o) {
        return DynamicObjects.serialize(o);
    }

    /**
     * Deserializes a DynamicObject from a String.
     *
     * @param edn  The Edn representation of the object.
     * @param type The type of class to deserialize. Must be an interface that extends DynamicObject.
     */
    public static > T deserialize(String edn, Class type) {
        return DynamicObjects.deserialize(edn, type);
    }

    /**
     * Use the supplied {@code map} to back an instance of {@code type}.
     */
    public static > T wrap(Object map, Class type) {
        return DynamicObjects.wrap(map, type);
    }

    /**
     * Create a "blank" instance of {@code type}, backed by an empty Clojure map. All fields will be null.
     */
    public static > T newInstance(Class type) {
        return DynamicObjects.newInstance(type);
    }

    /**
     * Register an {@link EdnTranslator} to enable instances of {@code type} to be serialized to and deserialized from
     * Edn using reader tags.
     */
    public static  void registerType(Class type, EdnTranslator translator) {
        DynamicObjects.registerType(type, translator);
    }

    /**
     * Deregister the given {@code translator}. After this method is invoked, it will no longer be possible to read or
     * write instances of {@code type} unless another translator is registered.
     */
    public static  void deregisterType(Class type) {
        DynamicObjects.deregisterType(type);
    }

    /**
     * Register a reader tag for a DynamicObject type. This is useful for reading Edn representations of Clojure
     * records.
     */
    public static > void registerTag(Class type, String tag) {
        DynamicObjects.registerTag(type, tag);
    }

    /**
     * Deregister the reader tag for the given DynamicObject type.
     */
    public static > void deregisterTag(Class type) {
        DynamicObjects.deregisterTag(type);
    }
}