(Post title shenanigans alert!)

This is a quick note for a few seemingly-simple issues about how clojure interops with java. And how I was surprised by it. Again. I'm also hoping it's useful and/or informative.

With clojure you can create "java" classes using the gen-class macro. With this macro you may construct a class in clojure, specify which interfaces it implements, what state it has and so on. Read more about gen-class at clojuredocs. It's not used often, but it can be necessary in some cases.

I encountered a few problems for which the solutions were not obvious and decided to collect it here in the form of examples.

Creating context; Most basic gen-class example

• We have one interface, IThing which we will implement in clojure.
• We have one java class ThingUser.
• ThingUser uses an instance of IThing.
• We will instantiate ThingUser from clojure, and give it our implementation of IThing.

To start with; Notice that IThing has two overloads defined on doWithThing1. Each takes a different number of parameters. (I'll use doWithThing2 and doWithThing3 lower down in this article.)

In package test;

public interface IThing {
    void doWithThing1(String a, String b);
    void doWithThing1(String a, String b, String c);

    void doWithThing2(String a, String b);
    void doWithThing2(String a, Integer b);
    void doWithThing2(Integer a, byte[] b);

    default void doWithThing3(String a, String b) {
        doWithThing2(a, b);
    }

}

public class ThingUser {
    public void doThingOneWithTwo(IThing thing) {
        thing.doWithThing1("A", "B");
    }
    public void doThingOneWithThree(IThing thing) {
        thing.doWithThing1("A", "B", "C");
    }
}

In test/thingi.clj:

(ns test.thingi
  (:import
   [test IThing ThingUser]))

(gen-class :name "test.thingi.TestImpl"
           :prefix "impl-"
           :main false
           :implements [test.IThing])

(defn impl-doWithThing1
  ([this a b c]
   (println (str "a: " a 
                 ", b: " b 
                 ", c: " c)))
  ([_this a b]
   (println (str "a: " a 
                 ", b: " b))))

Then in the repl evaluate this: (compile 'test.thingi). At this point everything is ready for the first test.

(let [impl (test.thingi.TestImpl.)
        user (ThingUser.)]
    (.doThingOneWithTwo user impl)
    (.doThingOneWithThree user impl))

a: A, b: B
a: A, b: B, c: C

Observations

• The interface method arity is matched to the correct clojure function arity.
• We are not "implementing" all of the interface methods on the clojure side yet no errors result.
• (compile ...) creates a stub .class by using the bytecodes API. This class is loaded once it is referenced in clojure.
• You can change the clojure code without having to restart the JVM. The stub methods use "reflection" to find the correct clojure functions.
• By default the class files are only loaded once per JVM. When the class file has to meaningfully change the JVM has to be restarted. There are tools that remove some of this friction.

same arity overloads

In IThing we are now looking at doWithThing2. Add new java class ThingUser2:

public class ThingUser2 {
    public void doThingTwo(IThing thing, String a, String b) {
        thing.doWithThing2(a, b);
    }
    public void doThingTwo(IThing thing, String a, Integer b) {
        thing.doWithThing2(a, b);
    }
    public void doThingTwo(IThing thing, Integer a, byte[] b) {
        thing.doWithThing2(a, b);
    }

In test/thingi.clj add:

(defn impl-doWithThing2
  [_ a b]
  (println (str "a[" (type a) "]: " a "\n"
                "b[" (type b) "]: " b)))

Then eval:

  (let [impl (test.thingi.TestImpl.)
        user (ThingUser2.)]
    (.doThingTwo user impl "a" "b")
    (.doThingTwo user impl "a" (int 66))
    (.doThingTwo user impl (int 65) ^bytes (.getBytes "b")))

I get this result:

a[class java.lang.String]: a
b[class java.lang.String]: b

a[class java.lang.String]: a
b[class java.lang.Integer]: 66

a[class java.lang.Integer]: 65
b[class [B]: [B@3ea69f14

Observations

• Regardless of which type arity overload you call, it will find the same function on the clojure side.
• Your logic will (probably) require some type inspection on the parameters.
• If the interface you implement gets a new overload with parameter types you did not anticipate you might get in trouble. Code defensively for this.

Alternative for overloads differing on parameter types

There is a secret (implementation detail) in the clojure compiler that allows you to create specific functions for gen-class methods, when the overloads differ only in the types of the parameters.

;; My recommendation is not to mix the two styles of implementation
;; (defn impl-doWithThing2
;;   [_ a b]
;;   (println (str "a[" (type a) "]: " a "\n"
;;                 "b[" (type b) "]: " b)))

(defn impl-doWithThing2-String-String
  [_ ^String a ^String b]
  (println "impl-doWithThing2-String-String: a=" a ", b=" b))

(defn impl-doWithThing2-String-Integer
  [_ ^String a ^Integer b]
  (println "impl-doWithThing2-String-Integer a=" a ", b=" b))

(defn impl-doWithThing2-Integer-byte<>
  [_ ^Integer a ^bytes b]
  (println "impl-doWithThing2-Integer-byte<> a=" a ", b=" (String. b)))

With the same test in the repl:

(let [impl (test.thingi.TestImpl.)
        user (ThingUser2.)]
    (.doThingTwo user impl "a" "b")
    (.doThingTwo user impl "a" (int 66))
    (.doThingTwo user impl (int 65) ^bytes (.getBytes "b")))

I get:

impl-doWithThing2-String-String: a= a , b= b
impl-doWithThing2-String-Integer a= a , b= 66
impl-doWithThing2-Integer-byte<> a= 65 , b= b

Observations

• The short names of the parameter types are taken, interleaved with -, and appended to the function name to specify the specific overload that is being defined.
• The short-name of an array is type[], for example int[], byte[] &c. [ and ] are special characters in clojure and cannot be used for the name of functions. They become <> in this case.
• In my opinion mixing the two ways of defining the implementation will most likely lead to bad results so I recommend you choose between inspecting the types at runtime, or specifying multiple functions one for each overload.

Default interface implementations

In java you can add a default implementation to an interface, which allows you to add backwards compatible updates to an interface. However ... (foreboding)

One more java class:

package test;

public class ThingUser3 {
    public void doThingThree(IThing thing, String a, String b) {
    thing.doWithThing3(a, b);
    }
}

Then I run this in the repl:

  (let [impl (test.thingi.TestImpl.)
        user (ThingUser3.)]
    (.doThingThree user impl "a" "b"))

For me, on clojure version 1.11.1 this fails with:

1. Unhandled java.lang.UnsupportedOperationException
   doWithThing3 (test.thingi/impl-doWithThing3 not defined?)

           ThingUser3.java:    5  test.ThingUser3/doThingThree
                      REPL:   55  test.thingi/eval11229
                      REPL:   53  test.thingi/eval11229
...

Whoops! There is a bug in the clojure compiler where it will implement doWithThing3 on the stub implementation and then look for the impl- function and not find it and then give this error.

This is on the clojure team's radar for maybe inclusion in 1.13.

I found this in kafka client code. We implement org.apache.kafka.common.serialization.Deserializer which in the most recent release (3.6) received a new interface method with a default implementation. If you do the same in clojure you will probably find it sooner or later too.

// old interface method
deserialize(String topic, Headers headers, byte[] data)
// new interface method overload
deserialize(String topic, Headers headers, ByteBuffer data)

What was a backwards compatible change in other JVM languages was a breaking change in clojure.

Observations

• I suspect the technique of runtime-type-inspecting the arguments is probably the one you are "supposed" to be using.
• The mechanism for naming a function after the types of parameters was added for a reason (which can only be guessed at).
• For better or for worse people (like myself) now depend on it.
• This mechanism is considered an implementation detail and the clojure team does not promise not to break it in the future.
• For particularly hairy interop situations, you are encouraged to use Java implementations. (I don't have a source reference for this)

References

• The original clojure mailing list post in which the secret gen-class overloading mechanism is discussed.
• At least one StackOverflow post in which the post above is referenced and the technique provided as an answer.
• Clojure Jira ticket for default implementations bug.
• Slack thread of Alex Miller predicting when default implementations might get support.

Did you know?

• the inventor of the (computer) keyboard died in 1890
• the inventor of the (computer) mouse was born 1925
  

The keyboard as a concept for operating a machine was around for at least 35 years before the mouse came to be. And I'm actually talking nonsense, because it was longer than that. (quick mafs)

And yet.

Building a web application to be used by a mouse is easy, reliable and expected. Building a web application so that it can be driven by a keyboard is at best a character building affair.

If you are a web developer in 2023 and your boss/friend/archenemy sweetly asks you to Add Keyboard shortcuts to your company's web app, tell them/they to go f**k themselves do it themselves instead.

Here's a short list of things that will mess with your self-confidence as a developer along the way:

• Most npm libraries that "deal with" keyboard events use the old and deprecated keyCode API. This API gives you a number to represent the key that was pressed. 38, 38, 40, 40, 37, 39, 37, 39, 66, 65.
• There is a new API that will tell you what key was pressed by using a set of well-define strings: ["ArrowUp", "ArrowUp", "ArrowDown", "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowLeft", "ArrowRight", "KeyB", "KeyA"].
• This is cool. I approve of this. 🫶
  
• This is (only somewhat) useful to you if you want to create keyboard shortcuts that are based on what motion your hand makes as they type those shortcuts.
  
• Part of the new API is the attribute called "key", which lets you know what character was produced by the keyboard, by the operating system, by the keyboard layout in the operating system, and by the browser inside this operating system. To quote from the spec:
  

  The "Digit2" and "KeyQ" keys are writing system keys that generate "2" and "q" when the US locale is active and "é" and "a" when the French locale is active.

• Keyboard layouts exist:
• Keyboard layouts are a software feature provided by your operating system, that makes a different character come out from the software than the one that was pressed by your fingers.
  
• People in other countries (not the US) speak languages with characters that cannot be found on a US keyboard.
• They prefer to use their keyboards to type words that are not in an English dictionary. (French, Greek, Hebrew)
  
• These are innocently called International Keyboard Layouts.
• Some nerds like to use US keyboards, but remap the keys to mean something different than what is printed on them. (Dvorak, Colemak)
• Some nerds build their own keyboards 😱 and I promise you you have no idea what will happen when they press a key on it.
• There is a javascript API that will tell you what character will come out of the mess that is a modern software stack when a specific, named key is pressed.
• Just don't have users who use Firefox ...
• or Safari.
• There is NOT an API that will tell you which key must be pressed in order to produce a specific character. (As an implementer of technologies, I understand, but as a user of technologies, this seems silly)
• Keyboards have things called "Modifier keys" on them: Alt, Shift, Control, Meta and some less well-known others AltGr, Hyper, Super, Fn
• Those things modify the meaning of the key that is pressed. Typically you hold down one (or more) of these keys while simultaneously pressing another key.
• Ctrl-S (means save in most places), Ctrl-Z (undo)
• Shift-a (means A in most places) etc.
• Most operating systems have opinions about what those modifier keys might be used for.
• On Windows, you cannot use Alt-F4 as a keyboard shortcut for anything. Meta-l (Windows L) is also usually off-limits.
• On MacOSX, pressing the Alt key changes the character of the key being pressed: Alt-J -> Δ
• On linux, with some window managers, Alt is reserved for dragging a window around. On other linuxes (linuxii?) anything else is possible.
• "Keyboard events" come in flavours: KeyDown, KeyPress & KeyUp
• If you hold a key down, it is the KeyDown event that is repeated. This is useful for panning, zooming or adding horizontal whitespace. (just kidding, do you think I'm a barbarian?!)
• The KeyPress event comes between the KeyDown and the KeyUp event. Sometimes.
• KeyUp is a decent choice for creating keychords with. (A keychord is a sequence of key presses that together triggers some action)
• On MacOSX, when you hold down the Meta key, KeyUp's sometimes/often don't fire.
• These things exist:
• Compose keys; quoting from Wikipedia:
  

  A compose key (sometimes called multi key) is a key on a computer keyboard that indicates that the following (usually 2 or more) keystrokes trigger the insertion of an alternate character, typically a precomposed character or a symbol. For instance, typing Compose followed by ~ and then n will insert ñ.

• Dead keys:
  

  A dead key is a special kind of modifier key on a mechanical typewriter, or computer keyboard, that is typically used to attach a specific diacritic to a base letter.

• Alt-codes (on Windows, I believe). Example: In Afrikaans words such as these exist: wêreld & sēening. To produce those characters on a Windows PC you hold down Alt and press in sequence 136 or 137, as the case may be.
• There's more in this category, but these are the ones I myself have used.
  
• Languages that have nothing to do with ancient Rome and Latin and of which I know nothing:
  
• 한글 (Korean)
• にほん · 日本 (Japan)
• 汉字 (China)
• עִברִית (Israel)

• हिंदी or தமிழ் or മലയാളം (merely 3 picked at random from Indian subcontinent)

• Ask yourself how people who speak (and type!) in these languages use computers created by white, English-speaking men.
  

… today I jumped off of a perfectly good bridge.

I have three siblings. All of my brothers are siblings. 2 of my siblings have two brothers each. One of my brothers only has me as a sibling.

I've been invited to speak at devopsdays 2018 Cape Town on the 20th of September 2018.

My talk will be about Hashicorp's nomad, a job schedule. 

Here are my conference slides for future posterity.

EDIT:

I'm adding a link to the source code of the slides on here too.

Seriously. Please give the slides a look so what I'm about to say makes sense, it'll take you 2 seconds. The link takes you to a single-page html/javascript app that I use whenever I have to present ideas to groups of people. I run that code on my laptop and connect an HDMI for the overhead projector...

The counter argument is that syntax sometimes aids in readability. I don't know about that, to be honest. If you can get by without syntax, then you're left with the meaning behind the code. And if you express the meaning meaningfully, then you get a piece of code that's a delight to work with.

(PS/rant - I hate traditional slide-deck software. I'd rather edit a piece of code to build my slide content than dick around with a mouse and icons I can barely see.)

I got this from a whatsapp group I belong to. OMG. A child drew this. I can believe. 🙏🏼

FIRST STEPS
===========

 - What am I trying to do?
 - Has it been done before?
 - Does it have a name?

-- Programming Buddha

When the student is ready the master appears

I am finding myself drawn, more and more, into my latent spirituality.  Everything is connected. There is no beginning and there is no end. However, one has to start somewhere. This introductory video is as good as any other starting point. Enjoy!

Come, Blessed One, we pray Thee, roll the wheel of the dew-sweet Law – which is excellent in the beginning, excellent in the middle, and excellent in the end! – Lotus Sutra

It is a great privilege to be able to share a few days worth of work.

Online copy of the Diamond Sutra.

The Nature of Mind

No words can describe it
No example can point to it
Samsara does not make it worse
Nirvana does not make it better
It has never been born
It has never ceased
It has never been liberated
It has never been deluded
It has never existed
It has never been nonexistent
It has no limits at all
It does not fall into any kind of category.

~ Dudjom Rinpoche

I have been doing naughty things at great speed on the various highways that we have here in Cape Town. My recent purchase of an over-powered and over-powering "Commuting Bike" has been causing me to invent reasons for getting around Town. A lot. I also usually need to get wherever I need to be really quickly... Therefore, I notice that we have excellent roads with nice grippy tar every time I find myself entering some corner at an absurd lean-angle by accident. 

I have been riding on some very nice roads recently and I am very, very grateful. The stack of speeding fines in my drawer carries with it a monetary value to my gratefulness. 

ONE of those roads is called Helen Suzman Blvd and the thought has often entered my mind that I wonder who she was and what she had to do to have a nice road named after her in the New South Africa

I am also lazy and have left actually finding out to apparently right now.

I just saw this video courtesy of The South African. 

It is interesting! The #DA made it and I have to say it is very, very self-congratulatory, but that's OK. I like it anyway. Enough to want to say "Ek stem saam!" out in public.

U edel-agbare. Ek stem saam.

Edit: You might have heard of the Helen Suzman Foundation, which has been in the news recently.

Ven Fifth Minyak Rinpoche visits Cape Town Kagyu in the beginning of August 2016. 

Here is a link to the Cape Town Kagyu website with the details of the program.

I also went ahead and created a public google calendar for these events. 

Do you remember the Sandra Bullock movie Gravity in which all kinds of shit goes down in space? Turns out, that actually happened. 

But it wasn't actually Sandra Bullock, it was one NASA astronaut and two Russian Cosmonauts. And it wasn't the ISS, it was Mir space station.

http://www.bbc.com/news/magazine–36549109

They survived...

Linenger was succeeded by Anglo-American astronaut Michael Foale, carried up by Atlantis on STS-84, alongside Russian mission specialist Elena Kondakova. Foale's increment proceeded fairly normally until 25 June when during the second test of the Progress manual docking system, TORU, Progress M-34 collided with solar arrays on the Spektr module and crashed into the module's outer shell, puncturing the module and causing depressurisation on the station. Only quick actions on the part of the crew, cutting cables leading to the module and closing Spektr's hatch, prevented the crews having to abandon the station in Soyuz TM-25. Their efforts stabilised the station's air pressure, whilst the pressure in Spektr, containing many of Foale's experiments and personal effects, dropped to a vacuum. In an effort to restore some of the power and systems lost following the isolation of Spektr and to attempt to locate the leak, EO-24 commander Anatoly Solovyev and flight engineer Pavel Vinogradov carried out a risky salvage operation later in the flight, entering the empty module during a so-called "intra-vehicular activity" or "IVA" spacewalk and inspecting the condition of hardware and running cables through a special hatch from Spektr's systems to the rest of the station. Following these first investigations, Foale and Solovyev conducted a 6-hour EVA outside Spektr to inspect the damage.