Guide for clojure's datatype constructs

content/guides/clj_datatype_constructs.adoc

@@ -0,0 +1,162 @@
+= Understanding Clojure's Datatype Constructs
+Ikuru Kanuma
+2017-07-20
+:type: guides
+:toc: macro
+:icons: font
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+== Goals of this guide
+
+Clojure supports several constructs for speaking to the Java world
+and/or creating types for polymorphic dispatch. +
+Because these constructs have overlapping capabilities, it may be confusing to know which construct to use at a given situation. +
+This guide clarifies what each construct is good at, while presenting minimal usage examples.
+
+== Proxy a Java class and/or Interfaces
+
+The proxy macro can be used to create an adhoc object that extends a Java Class.
+The example below extends the good old java.util.ArrayList such that a Clojure vector
+wrapped in an atom is used internally to manage state.
+
+[source,clojure-repl]
+----
+(import 'java.util.ArrayList)
+
+(def px (let [atm (atom [])]
+          (proxy [ArrayList] []
+            (add [e]
+              (swap! atm #(conj % e))
+              true)
+            (get [idx]
+              (get @atm idx))
+            (size [] (count @atm)))))
+
+(dotimes [n 10]
+  (.add px n))
+;; => nil
+(.get px 0)
+;; => 0
+(.get px 6)
+;; => 6
+(.size px)
+;; => 10
+----
+The ad hoc object can also implement Java Interfaces:
+
+[source,clojure-repl]
+----
+(import 'java.io.Closeable)
+(import 'java.util.concurrent.Callable)
+
+(def px (let [atm (atom [])]
+          (proxy [ArrayList Closeable Callable] []
+            (add [e]
+              (swap! atm #(conj % e))
+              true)
+            (get [idx]
+              (get @atm idx))
+            (size [] (count @atm))
+            (call []
+              (prn "Someone called me!"))
+            (close []
+              (prn "closing!")))))
+
+(.close px)
+"closing!"
+nil
+(.call px)
+"Someone called me!"
+nil
+----
+
+== Leaving Java with defrecord
+
+So far this is all dealing with Java stuff from Clojure. +
+If we do not have to extend from a concrete Java Type, we can define our own types
+that implement interfaces (and protocols, coming up next!) from Clojure via the
+link:https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/defrecord[defrecord] macro:
+
+[source,clojure-repl]
+----
+user=> (defrecord Foo [a b]
+         Closeable
+         (close [this]
+           (prn (+ a b))))
+user.Foo
+user=> (.close (Foo. 2 2))
+4
+nil
+----
+
+Records are nicer than Java classes for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference].
+
+https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/deftype[deftype] is
+also available for implementing lower level constructs that require mutatable fields.
+
+== Protocols; like Java Interfaces, but better
+https://clojure.org/reference/protocols[Protocols] offer similar capabilities as Java interfaces, but are more powerful because:
+
+* They are a cross platform construct
+* They allow third party types to participate in any protocols
+
+Let's make a protocol that handles Java ArrayList instances as well as Foo records:
+
+[source,clojure-repl]
+----
+user=> (defprotocol IBaz
+         (baz [this]))
+
+user=> (extend-protocol IBaz
+         ArrayList ;;A Java Class
+         (baz [this]
+           "ArrayList Baz")
+         Foo ;;A Clojure Record
+         (baz [this]
+           "Foo Baz"))
+nil
+user=> (baz (ArrayList.))
+"ArrayList Baz"
+user=> (baz (Foo. 1 1))
+"Foo Baz"
+----
+
+The main thing to realize here is that protocols are more powerful than interfaces because we are able to create custom abstraction for types that we do not control (e.g. java.util.Date). +
+If we were to apply a custom abstraction for Java Dates with an Interface IBaz,
+we must:
+
+* Go to the original source code of java.util.Date and say it implements IBaz
+* Also add IBaz to the official jdk release
+
+Unlikely to happen, right?
+
+== Reify-ing Java Interfaces or Protocols
+Sometimes we want to create things that implement a Protocol/Interface but do not want to give it a name for each of them. link:https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reify[reify] does exactly that:
+
+[source,clojure-repl]
+----
+user=> (def rf (reify
+                 Closeable
+                 (close [this]
+                   (prn "reified closing!!"))
+                 IBaz
+                 (baz [this]
+                   "reified baz")))
+nil
+user=> (baz rf)
+"reified baz"
+user=> (.close rf)
+"reified closing!!"
+nil
+----
+
+One might ask "Doesn't proxy achieve the same if you do not need to extend a concrete Type?" +
+The answer is reify has better performance.
+
+== Take away
+To wrap up, here are some rules of thumb:
+
+* Prefer protocols and records over Java Types; stay in Clojure
+* If you must extend a Java Class, use proxy
+* If you want an anonymous implementation of a Protocol/Interface, use reify