Incorporate feedback

content/guides/clj_datatype_constructs.adoc

@@ -1,4 +1,4 @@
-= Understanding Clojure's Polymorphism
+= Understanding Clojure's Datatype Constructs
 Ikuru Kanuma
 2017-07-20
 :type: guides
@@ -10,63 +10,70 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 == Goals of this guide
 
 Clojure supports several constructs for speaking to the Java world
-and creating types for polymorphic dispatch. +
+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. +
-Hopefully this guide clarifies what each construct is good at, while presenting minimal usage examples.
-
-== Warm up with some Java
-
-Let's warm up with some Java interop:
-
-[source,clojure-repl]
-----
-user=> (import 'java.util.Date)
-java.util.Date
-user=> (.toString (Date.))
-"Fri Jul 21 11:40:49 JST 2017"
-----
-
-Java Interop works. Cool!
+This guide clarifies what each construct is good at, while presenting minimal usage examples.
 
 == Proxy a Java class and/or Interfaces
 
-Say we want the .toString method to add a greeting at the beginning for friendlyness. +
-The proxy macro can be used to create an adhoc object that extends a Java Class:
+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]
 ----
-user=> (def px (proxy [Date] []
-                 (toString []
-                    (str "Hello there! It is now "
-                         (proxy-super toString)))))
-user=> (.toString px)
-"Hello there! It is now Fri Jul 21 11:48:14 JST 2017"
+(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)
-user=> (def px (proxy [Date Callable Closeable] []
-                 (toString []
-                   (str "Hello there! It is now "
-                        (proxy-super toString)))
-                 (call []
-                   (prn "Someone called me!"))
-                 (close []
-                   (prn "closing!"))))
-user=> (.close px)
+
+(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
-user=> (.call px)
+(.call px)
 "Someone called me!"
 nil
 ----
 
 == Leaving Java with defrecord
 
-Sofar this is all dealing with Java stuff from Clojure. +
+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:
@@ -83,37 +90,39 @@ user=> (.close (Foo. 2 2))
 nil
 ----
 
-Records are nicer for the reasons described in the https://clojure.org/reference/datatypes#_deftype_and_defrecord[reference].
+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 is more powerfuld because:
+https://clojure.org/reference/protocols[Protocols] offer similar capabilities as Java interfaces, but are more powerful because:
 
-* It is a cross platform construct
-* It allows third party types to participate in any protocols
+* They are a cross platform construct
+* They allow third party types to participate in any protocols
 
-Let's make a protocol that handles Java Date instances as well as Foo records:
+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
-         Date;;Thing from Java
+         ArrayList ;;A Java Class
          (baz [this]
-           (str "baz method for a Date: "
-                (.toString this)))
-         Foo;;Clojure Record
+           "ArrayList Baz")
+         Foo ;;A Clojure Record
          (baz [this]
-            (str "baz method for a Foo record!")))
+           "Foo Baz"))
 nil
-user=> (baz (Date.))
-"baz method for a Date: Fri Jul 21 14:04:46 JST 2017"
+user=> (baz (ArrayList.))
+"ArrayList Baz"
 user=> (baz (Foo. 1 1))
-"baz method for a Foo record!"
+"Foo Bax"
 ----
 
-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). +
+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:
 
@@ -150,4 +159,4 @@ 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 a one-off implementation of a Protocol/Interface, use reify
+* If you want an anonymous implementation of a Protocol/Interface, use reify