I need another two devs

G'day:

On hold

I am still looking for two devs, but the exact job spec is being revised. So… well… ignore this for now.

I've previously posted similar offerings:

• Work with me here
• Work with me here - revisited
• Work with me here - revisited …again

We are growing our team some more, this time looking for two devs. Previously we'd only been hiring senior / very experienced CFML engineers; this time I'm happy to talk to more mid-level devs who might like to join a team of seniors and take an opportunity to improve their CFML skills, and their general engineering skills.

We have a B2B app running on CFWheels (but don't let that worry you; very little of the work really involves anything to do with Wheels itself), that requires ongoing support, maintenance, and new development.

We are starting to port away from CFML and replatforming on Kotlin, and there'll be opportunity to come along on that ride as well, although the primary focus in the medium term is supporting the CFML platform. This is the platform that makes all our money and pays all our wages, and is under active development still. I don't want to make this sound like this is just a maintenance role on a legacy platform because we have a shiny new platform too. That's not the case at all. This is a strong CFML job, and we all do CFML every day.

The details of the role - which I've lifted from our ad: "Application Developer (UK)" - are:

Competencies:

• Experience with CFML.
• Experience maintaining and building on existing legacy applications.
• Experience developing new web applications/web services.

Highly desirable:

• Some exposure to test automation (eg: unit testing).
• Exposure to OOP development practices in CFML.
• Some knowledge of design principles such as MVC, SOLID and other common design patterns.
• Experience with React.js or similar client-side application technology.
• Experience with TDD practices.
• Some familiarity with Dockerised development environments.
• Some familiarity with Agile principles, and experience delivering value in an Agile fashion.
• Experience with CFWheels.

Logistics-wise this is a permanent (ie: we are not offering it to contractors) remote-first position within the UK. I will not consider any other "unofficial" attempts to work from an offshore location. You must be resident in the UK, and be able to work here. We have an office but I've never set foot in it. But if you want to work in Bournemouth, there's a desk for you there if that's your thing. The non-dev ppl in that office are all nice :-).

Secondly, we are only able to hire employees who are able to live and work in the UK without visa sponsorship.

We have two openings for this role at the moment.

I see this as a good role for a person who's reasonably competent in CFML but feel there's room to improve, and would like the opportunity to join an existing experienced team whose aim is to enhance everyone's game. Maybe you're comfortable with CFML but not getting a chance to stretch yourself in your current role? Drop me a line.

If you want to have a chat about this, you can ping me in the CFML Slack channel (if for some reason you're a CFML dev reading this and not already in here, you can join via cfml-slack.herokuapp.com). Or you can send yer CV through to the email address on the job spec page linked-to above. I'm not interested in talking to recruiters for now, just in case you are one (and reading this?). For now I'm only wanting to talk to people in the dev community directly.

Righto.

--
Adam

Off-topic / no technical content: I have a dilemma

G'day:

This is off-topic and has no technical content to it at all. It is about a personal situation I have. This is the only place I have to post large wodges of text publicly, hence putting it here. And hey it's my blog: I'll post what I want ;-)

I have a dilemma.

Context / history

My neighbour and I share a front door to the street, and we had got onto nodding terms with each other. When her new baby arrived I fussed a bit over the new wee girl and got to talking more. My neighbour has three girls, approximately 15, 8, <1. They live in a flat that is at most 2 bedrooms. It will be like mine, which is to say it will be very very basic.

She is on a key meter for her electricty, and these display the balance on the meter, which is inside the front door, so I pass it daily. Often (once a month? Every coupla months?) it's in the red, and their power is off.

We each pay for one of the lights in the shared area (stairs, hallway to the front door), and I have been making a point of giving her £20 every few months to cover her share of it.

She has had bailiffs around chasing her ex, who owes the council money for parking fines.

She has had the police around to escort her current partner away from the flat, as he was being abusive. He is, btw, back.

Someone from a charity brought a bag of food around "for the lady who lives upstairs with the kids. She looks like she could do with some food".

I think it's reasonable to say she's struggling with life.

Recently she came to me in a flap saying she hd a debt she needed to pay now, and she couldn't and could she borrow £20? I offered £50, and she did not hesitate to take it. I told her she did not have to pay me back as I could afford it, and she needed it more than me. This is not terribly altruistic of me: I give £50 to charity each month, and that month I gave it to her instead. [shrug].

A few weeks later she texted me saying she needed another £20 in her account as she needed to pay a bill urgently. And she'd pay me back. I transferred £50, and reassured her she didn't need to pay me back, but that we can't keep operating like this.

She's knocked on the door to give me £20 back - I reiterated she didn't need to but she insisted - but within the day she meekly came back and asked if she could take it back again. Because reasons. Fine.

This is all fine. Thusfar.

However now she is texting me every week almost for more money, and I have drawn a line under this enterprise saying "look, 'borrowing' money from your neighbour is not a workable way of solving your issues. I don't know what is, but this has to stop. Please don't ask me for more money".

The calls/texts continue. I am ignoring them. She is still friendly when I meet her on the landing or on the street.

She has actually paid back the £120 she ended up "owing" me. I asked he to keep it: she refused.

Here is my dilemma

She's broke. The UK is not a good place to be broke. Social services are struggling, food banks are struggling. Really a lot of people are struggling. I don't want anyone reading this as anything as a fact that is contextually significant: she is from an eastern European country, her English is not great and I suspect her education is not great either. She does not appear to have any family over here.

On the other hand I am not struggling. I can afford to just give her the money (and I can also afford to also keep giving £££ to charity each month too if I wanted to). I'm not a fountain of cash, but £50 here or there doesn't matter.

Theoretically I stand by my position of "asking yer neighbour for money is not a sustainable solution to your problems". But she has kids who need to eat & have a roof & be warm. Should theoretical economics trump hungry kids?

I have found myself thinking "this is not my problem" or "this should not *be* my problem". But it's my neighbour. Someone in my community. Who needs help and has asked for help.

Whether or not the govt or local council should be dealing with this is neither here nor there. We have a shit, evil (actually evil) government, and we know they don't give a shit about poor people. I can't change the govt (other than one vote at a time), but I can change this situation maybe.

I feel I am being more "middle-class" than I am being a caring person. But all the points above nag at me. I'm currently holding the position of "no, no more money; I am not the solution to your problems". But I suspect I might be mistaken, or being overly "priveleged" about this because I can afford to prevaricate over principles vs hunger.

Thoughts? And if you don't wanna put them publicly here, my email address is on the blog's Communications policy page. Or a lot of my readers know other channels to ping me on and discuss.

Righto.

--
Adam

Kotlin: more operator overloading

G'day:

The Kotlin koans are still focusing on operator overloading, so so am I. Previously (Kotlin: overriding operators), I had a mess around with overloading:

• unary plus operator
• compareTo operator
• indexed access operator

This evening I'm gonna look at a coupla others.

Plus operator

Like… just the + operator. As in a + b.

This is a daft example, but I'm gonna define a buildable Critter class. A Critter can have a number of arms, legs and heads. Why? Oh I don't know. It just seemed funny to me at the time.

To do this I need to overload the plus operator multiple times:

class Critter(){
    private var heads = mutableListOf<Head>()
    private var arms = mutableListOf<Arm>()
    private var legs = mutableListOf<Leg>()

    operator fun plus(head: Head) : Critter {
        heads.add(head)
        return this
    }
    operator fun plus(arm: Arm) : Critter {
        arms.add(arm)
        return this
    }
    operator fun plus(leg: Leg) : Critter  {
        legs.add(leg)
        return this
    }
}

I'm overloading the plus operator three times. One each for Critter + Head, Critter + Arm, Critter + Leg. Note also that I'm specifically returning the Critter itself from these operations, so that further operations can be chained.

For the purposes of this exercise, the Arm, Leg, Head classes are a bit light on implementation:

class Arm
class Leg
class Head

For the test, I've also added a helper method:

fun describe()= """
        Critter with ${heads.size} ${English.plural("head", heads.size)},
        and ${arms.size} ${English.plural("arm", arms.size)},
        and ${legs.size} ${English.plural("leg", legs.size)}
    """.trimIndent().replace("\n", " ")

(That pluralising thing is a third-party library I dug up. No need to worry about that just now).

And now we can have the rest of our test code (all the above was the "arrange" part of the test):

val critter = Critter()
critter + Head()
critter + Arm() + Arm()
critter + Leg() + Leg() + Leg() + Leg()

critter.describe() shouldBe "Critter with 1 head, and 2 arms, and 4 legs"

It's silly, but I quite like that.

For the sake of completeness, I've tested the chaining works with different types:

fun `it can mix-up the body parts` () {
    val critter = Critter() + Head() + Arm() + Leg() + Leg() + Arm() + Leg() + Head() + Leg()

    critter.describe() shouldBe "Critter with 2 heads, and 2 arms, and 4 legs"
}

---

Invoke operator

I've messed around with this sort of thing with PHP's __invoke before. The invoke operator function represents the () operator one calls functions with; IE: if f is the function, one uses the () operator to call it: f(). Implementing this operator on a class lets one call objects like methods. Should one want to do that. Which, admittedly, is pretty rarely. But still.

class Logger {
    private var _log = mutableListOf<String>()
    val log: List<String>
        get() = _log

    operator fun invoke(message: String) {
        _log += message
    }
}

Here I have a logger class whose objects can be called as methods:

val logMessage = Logger() // logMessage is an object: an instance of Logger
logMessage("This is a log message")
logMessage("This is another log message")

The bit that effects this is the invoke function.

And the assert part of the test:

logMessage.log shouldBe listOf("This is a log message", "This is another log message")

The next thing I thought to try is how I might have a variadic invoke function: one I can pass any number of arguments to. This example is a bit contrived, but it shows it. Here a Task is an object that is initialised with a lambda, and when the task is invoked as a function, it runs the lambda with whatever the invocation is passed:

class Task(var lambda : (args: Array<String>) -> List<String>) {
    operator fun invoke(vararg args: String) : List<String> {
        return lambda(arrayOf(*args))
    }
}

One thing that is annoying is that a lambda can't be defined as having a vararg parameter, so I need to use an array of things there. However the invoke function can use vararg, so that's cool.

The * there is the spread operator, which converts the varargs passed to the invoke call to an array that the lambda needs. I could not find any other docs for this other than a reference in the vararg docs linked in the previous paragraph.

So I create my task with its lambda:

val task = Task { args -> args.toList() }

And I check the results:

val taskResult = task("This", "is", "a", "variadic", "invoke", "handler")
taskResult shouldBe listOf("This", "is", "a", "variadic", "invoke", "handler")

Both those lines look similar, so it's important to note the first one is passing six separate arguments to task (which is an object remember, not a function!), and the second line is one list with six items. The lambda coverted the varargs from the invoke call to the list it returned.

---

And that is as far as I got tonight, so I'll leave off here.

Here's the code:

• OperatorOverloadingTest.kt
• InvokeTest.kt
• PluralizeTest.kt (that's some tests of that pluralisation lib I was using (atteo/evo-inflector)).

Righto.

--
Adam

Kotlin: ranges

G'day:

Yet another example of me starting a Kotlin koans exercise, seeing the first interesting word in the koans task description and getting lost in researching how the thing works.

Test class names

This is just an aside. You know how I've been showing all these test methods like this (spoiler for the next section):

@Test
fun `a range of integers should be an IntRange`() {
    val range = 1..10

    range.shouldBeInstanceOf<IntRange>()
}

Where the method name is in back-ticks and a human-readable sentence? On a whim I went "I wonder if…" and I tried this:

internal class `Tests of ranges` {

    @Nested
    inner class `Tests of ranges on Ints` {
    // etc

And it only bloody works on class names too! How cool is that?

In the test output that lot shows like this:

---

Ranges

From the docs:

A range defines a closed interval in the mathematical sense: it is defined by its two endpoint values which are both included in the range.

Let's look at some tests that show how they work:

fun `it should return true for a value in a range`() {
    val range = 1..10
    val value = 5

    (value in range) shouldBe true
}

fun `it should return false for a value not in a range`() {
    val range = 1..10
    val value = 11

    (value in range) shouldBe false
}

fun `it should return true for values at the boundaries of the range`() {
    val range = 1..10

    (1 in range) shouldBe true
    (10 in range) shouldBe true
}

Those are pretty straight forward. What type is it?

fun `a range of integers should be an IntRange`() {
    val range = 1..10

    range.shouldBeInstanceOf<IntRange>()
}

And how to use it?

fun `it can be iterated over`() {
    val range = 1..10
    var list = mutableListOf<Int>()

    list = range.fold(list) { acc, i -> acc.apply { add(i) } }

    list shouldBe listOf(1,2,3,4,5,6,7,8,9,10)
}

It can have a step:

fun `it should return true for values at the steps`() {
    val range = 1..10 step 2

    listOf(1,3,5,7,9).forEach {
        (it in range) shouldBe true
    }
}

Also be mindful of what elements are in the range:

@Test
fun `the upper bound might not be included`() {
    val range = 1 until 10 step 2

    (10 in range) shouldBe false
}

fun `it should return false for values not at the steps`() {
    val range = 1..10 step 2

    listOf(2,4,6,8,10).forEach {
        (it in range) shouldBe false
    }
}

Note the type on a stepped-range is different:

fun `a stepped range is an IntProgression`() {
    val range = 1..10 step 2

    range.shouldNotBeInstanceOf<IntRange>()
    range.shouldBeInstanceOf<IntProgression>()
}

They work in reverse:

fun `a step can be downwards`() {
    val range = 10 downTo 1 step 2

    listOf(10,8,6,4,2).forEach {
        (it in range) shouldBe true
    }
    (1 in range) shouldBe false
}

And one can access some properties about the range:

fun `it has some properties`() {
    val range = 1..10 step 2

    range.first shouldBe 1
    range.last shouldBe 9
    range.step shouldBe 2
}

Note how it's the max value here, not the upper bound of the range.

And they can be reversed (and by inference here, compared):

fun `it can be reversed`() {
    val range = 1..10 step 2
    val reversed = range.reversed()

    (reversed == (9 downTo 1 step 2)) shouldBe true
}

One can make a range of doubles, but they're not iterable:

fun `it does not implement iterator like a range of ints does`() {
    val intRange = 1..10
    intRange.shouldBeInstanceOf<Iterable<*>>()

    val doubleRange = 1.0..10.0
    doubleRange.shouldNotBeInstanceOf<Iterable<*>>()
}

However one can still check whether something is within the range:

fun `its elements can be compared to other values`() {
    val range = 1.0..10.0
    val value = 5.5

    (value in range) shouldBe true
}

Ranges of chars are more useful (I guess…):

fun `a range of chars can have a step`() {
    val range = 'z' downTo 'a' step 2

    listOf('z','x','v','t','r','p','n','l','j','h','f','d','b').forEach {
        (it in range) shouldBe true
    }
}

One can have ranges of strings, but they don't seem to support stepping or downto

fun `a range of strings can have a step`() {
    val range = "a".."f"

    listOf("a","b","c","d","e","f").forEach {
        (it in range) shouldBe true
    }
}

But they can be multi-char:

fun `the strings in the range can be multi-character`() {
    val range = "aa".."cc"

    listOf("aa","ab","ac","ba","bb","bc","ca","cb","cc").forEach {
        (it in range) shouldBe true
    }
}

I tried to be clever and create a range of strings and then reverse it, but Kotlin sez no:

I can make a range of enum elements (which I thought was at least a bit clever of me to try):

@Test
fun `a range of MaoriNumbersEnum should not allow other elements from the enum`() {
    val range = MI.TAHI..MI.WHA // tahi, rua, toru, wha

    (MI.RUA in range) shouldBe true
    (MI.RIMA in range) shouldBe false // rima is 5
}

@Test
fun `a range of enums is not iterable` () {
    val range = MI.TAHI..MI.WHA

    range.shouldNotBeInstanceOf<Iterable<*>>()
}

But as you can see, they too aren't iterable.

I think I need to set myself an assignment to write extension functions so I can iterate over my Maori numbers. But not this evening.

Lastly - and so I can answer the koans question - any class that implements Comparable can be used in a range.

Here's my MyDate class back from the previous article:

data class MyDate(val year: Int, val month: Int, val dayOfMonth: Int) : Comparable<MyDate> {
    override fun compareTo(other: MyDate): Int {
        return when {
            year != other.year -> year.compareTo(other.year)
            month != other.month -> month.compareTo(other.month)
            else -> dayOfMonth.compareTo(other.dayOfMonth)
        }
    }
}

And using it in a range:

fun `a range of objects implementing Comparable can be used as a range`() {
    val testDates = MyDate(1955, 3, 25)..MyDate(1955, 3, 28)

    testDates.start shouldBe MyDate(1955, 3, 25)
    testDates.endInclusive shouldBe MyDate(1955, 3, 28)

    val restDay = MyDate(1955, 3, 27)
    (restDay in testDates) shouldBe true
}

(26 bonus points for anyone who can work out what that date range is. There is a clue in there. And I doubt anyone who is not an NZ cricket fan has a hope in hell of getting it).

It looks like making an iterable range of MyDate objects isn't that hard (esp if I get Copilot to do a lot of it). First I need to implement a "next" method in MyDate:

data class MyDate(val year: Int, val month: Int, val dayOfMonth: Int) : Comparable<MyDate> {
    private val date = LocalDate.of(year, month, dayOfMonth)

    override fun compareTo(other: MyDate): Int {
        return when {
            year != other.year -> year.compareTo(other.year)
            month != other.month -> month.compareTo(other.month)
            else -> dayOfMonth.compareTo(other.dayOfMonth)
        }
    }

    fun nextDay(): MyDate {
        val nextDate = date.plusDays(1)
        return MyDate(nextDate.year, nextDate.monthValue, nextDate.dayOfMonth)
    }
}

Then I need to create the range class:

class MyDateRange(override val start: MyDate, override val endInclusive: MyDate) : ClosedRange<MyDate>, Iterable<MyDate> {
    override fun iterator(): Iterator<MyDate> {
        return object : Iterator<MyDate> {
            var current = start

            override fun hasNext(): Boolean {
                return current <= endInclusive
            }

            override fun next(): MyDate {
                val result = current
                current = current.nextDay()
                return result
            }
        }
    }
}

Copilot wrote all of that for me, once I gave it the class name, and then asked it to implement Iterable as well.

I have to admit I kinda spiked this code to see how hard it would be to implement before deciding whether to even include this in the article, so I back-filled the test on this one.

fun `an iterable range can be made by implementing Comparable and Iterable`() {
    val testDates = MyDateRange(MyDate(1955, 3, 25), MyDate(1955, 3, 28))

    (MyDate(1955, 3, 27) in testDates) shouldBe true
    (MyDate(1955, 3, 29) in testDates) shouldBe false

    var list = mutableListOf<MyDate>()

    list = testDates.fold(list) { acc, date -> acc.apply { add(date) } }

    list shouldBe listOf(
        MyDate(1955, 3, 25),
        MyDate(1955, 3, 26),
        MyDate(1955, 3, 27),
        MyDate(1955, 3, 28)
    )
}

This is a good start for me to work out how to make a fully-functioning enum range. Later.

And that is a chunk of code, and not much text. I think the tests largely speak for themselves; the only tricky bit was that last MyDateRange thing, and I'll come back to that. Lemme know if this strategy of using "tests as narrative" works? Cheers.

The code is here: RangesTest.kt.

Righto.

--
Adam

CFML: AND and OR operators not doing what one might expect

G'day:

A question came up on the CFML Slack forums today about some "unexpected behaviour" with ColdFusion's and operator. Here's an example (CF2021):

cf-cli>5 && 7
7

cf-cli>5 || 7
5

Compared to Lucee:

CFSCRIPT-REPL: 5  && 7
true
CFSCRIPT-REPL: 5 || 7
true

The questioner was puzzled by ColdFusion's behaviour, expecting to see something more like Lucee's result.

The docs for these (Expressions-Developing guide › Boolean operators) says this:

AND or &&

Return True if both arguments are True; return False otherwise. For example, True AND True is True, but True AND False is False.

On the face of it Lucee is getting it right, and ColdFusion is being weird, however this is a case of Lucee following the docs, and the docs being wrong.

CFML's behaviour with the AND and OR operators is not quite as the docs say, they behave the way described clearly in the JavaScript docs (JavaScript › Expressions and operators › Logical AND (&&)):

More generally, the operator returns the value of the first falsy operand encountered when evaluating from left to right, or the value of the last operand if they are all truthy.

I only cite the JS docs cos they're clear and well-worded, not because of any connection to CFML.

I guess it works like this in languages with truthy/falsy values as opposed to strict true/false because the operand-values can have meaning beyond just being boolean.

I checked some other languages I had to hand:

adam@DESKTOP-QV1A45U:~$ node -i
> 5 && 7
7
> 5 || 7
5

(And JS run in the browser is the same)

Ruby:

adam@DESKTOP-QV1A45U:~$ irb
irb(main):001:0> 5 && 7
=> 7
irb(main):002:0> 5 || 7
=> 5
irb(main):003:0>

Groovy:

groovy:000> 5 && 7
===> true
groovy:000> 5 || 7
===> true
groovy:000>

PHP:

php > echo 5 && 7;
1
php > echo 5 || 7;
1

Clojure:

user=> (and 5 7)
7
user=> (or 5 7)
5

There's a strong precedent there, but obviously it could have gone either way. CFML just went the way shown. So it's a bug in Lucee that it doesn't work the same as ColdFusion.

BTW: ColdFusion has worked that way since at least CF5. I just checked.

Why am I writing this? Well cos it's not correctly documented anywhere, so I figured I'd jot something down in the hope Google picks it up.

Righto.

--
Adam

Kotlin: overriding operators

G'day:

Apologies in advance if this article is a bit rubbish. I'm not really "feeling it" today with the writing, but I need to crack on with the Kotlin stuff so am hoping if I get a move on with something, I'll find my motivation as I go. This has never once worked in my life before, but let's see what happens this time.

---

Prelude

OK so the next Kotlin koans exercise is about operator overloading, hence looking at that now. My one enduring memory of when I did C++ back in polytech (this was in 1993 or 1994) was my tutor's advice re operator overloading: just because it's possible doesn't mean one should do it: it just makes for messy, hard to understand code. 28 years later (OMG: 28!!) I am using a language that supports operator overloading for the first time. I mean I've messed around with Ruby, Groovy etc which allow it, but I never got far enough with those to need to look at it.

I think this is possibly why I'm unmotivated to write on this: I need to know about it, but I don't really want to know about it, if you see what I mean. Anyway: harden up, Cameron. Get on with it.

---

Unary plus operator

The first interesting thing I landed on was the notion of a unary-plus operator. WTF? I knew what a unary-minus operator does: switches the sign on the operand. But what would a unary-plus operator do? The operator overloading docs page mentioned it but didn't explain it; and the operators listing in the docs (Keywords and operators › Operators and special symbols) didn't mention it at all (or unary-minus for that matter). I've just found there's a docs page for unary-plus specifically, and it says:

operator fun unaryPlus(): Int

Returns this value.

That was a bit unhelpful until I checked the equivlent page for unary-minus:

operator fun unaryMinus(): Int

Returns the negative of this value.

OK: got it. It literally just returns the value (constrast with the minus one that returns the negative of the value, to slightly belabour the point). This does not seem useful, so I figured I was missing something, so googled a bit. I found a doc somewhere (I can't find it now; I'm writing this a week after I did the initial research) that indicated it was added to either C or C++ for the sake of symmetry with unary-minus. I also found that in other languages it does actually have functionality on non-numeric types. In JavaScript it will return the numeric value of a string, eg:

s = "42"
'42'
+s 
42  

And in Java I found that it does similar. What is the purpose of Java's unary plus operator?:

The unary plus operator performs an automatic conversion to int when the type of its operand is byte, char, or short.

Let's have a look at that:

jshell> char c = 'A'
c ==> 'A'
|  created variable c : char

jshell> +c
$2 ==> 65
|  created scratch variable $2 : int

Fair enough. I can work with this.

I had a look at how the unary-plus operator works on the types that support it in Kotlin, with variations on this approach:

@Nested
@DisplayName("Tests of unary plus operator on Ints")
inner class IntUnaryPlusTest {

    @Test
    fun `it does nothing to integer values`() {
        +1 shouldBe 1
    }

    @Test
    fun `it throws a NPE for null Ints`() {
        val i: Int? = null

        shouldThrow<NullPointerException> {
            +i!!
        }
    }
}

I had a version of those for Ints, Doubles, Floats, Longs, Shorts and Bytes.

---

Operator overloading

Kotlin doesn't support the unary-plus operator on chars, so here's where my experimentation starts. It's pretty simple:

@Nested
@DisplayName("Tests of overloaded unary plus operator on Chars")
inner class CharUnaryPlusTest {
    operator fun Char?.unaryPlus(): Int? {
        return this?.code
    }

    @Test
    fun `it returns the character code of the char as an int`() {
        +'a' shouldBe 97
    }

    @Test
    fun `it returns null if the Char is null`() {
        val c: Char? = null

        val result = +c

        result.shouldBeNull()
    }

    @Test
    fun `it handles double-byte chars`() {
        +'€' shouldBe 8364
    }

    // NB: emoji will not fit into a Char see https://stackoverflow.com/q/70152643/894061
}

All one does is to create a method of your class or - in this case as I am "extending" a built-in class - an extension function, prefix it with "operator", and the method names for the various operators are listed on the docs page I link to in the heading. That's it.

I also did an implementation for Booleans:

operator fun Boolean?.unaryPlus(): Int {
    return if (this == true) 1 else 0
}

// ...

@Test
fun `it returns zero if the boolean is null`() {
    val b: Boolean? = null

    val result = +b

    result shouldBe 0
}

(I left the null test in as it wasn't so obvious: as an arbitrary decision I decided a null Boolean should behave as if it's falsey for this conversion. Equally it could have just stayed as a null).

I also did Strings:

@Nested
@DisplayName("Tests of overloaded unary plus operator on Strings")
inner class StringUnaryPlusTest {
    operator fun String?.unaryPlus(): Number? {
        return this?.toIntOrNull() ?: this?.toDoubleOrNull()
    }

    @Test
    fun `it converts a string integer to an Int`() {
        val result = +"42"

        result.shouldBeInstanceOf<Int>()
        result shouldBe 42
    }

    @Test
    fun `it handles negative numbers`() {
        +"-42" shouldBe -42
    }

    @Test
    fun `it converts a string double to a Double`() {
        val result = +"3.14"

        result.shouldBeInstanceOf<Double>()
        result shouldBe 3.14
    }

    @Test
    fun `it handles a null string`() {
        val s: String? = null

        val result = +s

        result.shouldBeNull()
    }

    @Test
    fun `it handles a string that is not a number`() {
        val s = "not a number"

        val result = +s

        result.shouldBeNull()
    }
}

Again the handling was an arbitrary one. I decided that if it could convert it to an Int, then an Int it will be. Otherwise a Double. Otherwise null.

I also let Copilot take over after the obvious cases. I typed the test label and let it do the rest. It wrote some more examples for collection types along these lines:

@Test
fun `unary plus is not implemented on Array values, but can be overloaded`() {
    operator fun Array<Int>.unaryPlus(): Int? {
        return this.sum()
    }
    +arrayOf(1, 2, 3) shouldBe 6
}

Indeed after the first one, I just had to write @Test and it got the idea. I won't repeat it all here as it's a bit "samey", but I'll include a link to GitHub at the bottom of the article.

---

Koans requirement: compareTo

That was a lot of digression away from what the exercise actually wanted, which is to implement date-comparison operations on bespoke date class. The example code is this:

data class MyDate(val year: Int, val month: Int, val dayOfMonth: Int) : Comparable<MyDate> {
    /* TODO */
}

And I need to be able to do this:

println(date1 < date2)

All this investigation into overloading unary operators has not helped here. I need to overload an operator that has two operands.

Copilot largely came to the rescue here. I created the test file and @DisplayName("Tests of overloading the compareTo operator on MyDate objects") and it created the test skeletons for me:

@Test
fun `it should returns 0 when the two MyDate objects are equal`() {
    TODO()
}

@Test
fun `it should returns -1 when the first MyDate object is less than the second MyDate object`() {
    TODO()
}

@Test
fun `it should returns 1 when the first MyDate object is greater than the second MyDate object`() {
    TODO()
}

It couldn't do better than that as it had no idea what this "MyDate" thing is that I'm on about. However once I typed data class MyDate, it got the idea and had a good stab at the solution:

data class MyDate(val year: Int, val month: Int, val dayOfMonth: Int) : Comparable<MyDate> {
    override fun compareTo(other: MyDate): Int {
        return when {
            year != other.year -> year - other.year
            month != other.month -> month - other.month
            else -> dayOfMonth - other.dayOfMonth
        }
    }
}

That would work OK, but it failed its own tests because it returned 5 for the comparison in the "less than" test (2016 - 2011 = 5). I coached it a bit, and we finally agreed on this:

override fun compareTo(other: MyDate): Int {
    return when {
        year != other.year -> year.compareTo(other.year)
        month != other.month -> month.compareTo(other.month)
        else -> dayOfMonth.compareTo(other.dayOfMonth)
    }
}

This way it returns one of -1, 0, 1, which is tidier than the actual difference, and has the added bonus of giving us passing tests.

I need one more test though. The requirement is not to us the compareTo method, it's to use the < operator. I will encourage Copilot to write this for me:

(It's only got the red squiggly line cos the function name isn't closed yet).

Nailed it, Copilot. Thanks.

I slung that into the koans window and checked it: pass. I checked their own implementation, and it was slightly simpler:

override fun compareTo(other: MyDate) = when {
    year != other.year -> year - other.year
    month != other.month -> month - other.month
    else -> dayOfMonth - other.dayOfMonth
}

All that when block is a single expression, so we could have eschewed the braces and the return. Good thinking.

---

Indexed access operator

I decided to do one last exercise. One can make an object accessible via index notation (eg: myObj[i]) via overloading the get operator.

Here's how we expect it to work:

import WordCollections.MaoriNumbersEnum as MI

// ...

@Test
fun `it should return the correct value for the given index`() {
    val numbers = MaoriNumbers(listOf(MI.TAHI,MI.RUA,MI.TORU,MI.WHA))

    numbers[0] shouldBe MI.TAHI
    numbers[1] shouldBe MI.RUA
    numbers[2] shouldBe MI.TORU
    numbers[3] shouldBe MI.WHA
}

And here's the implementation:

data class MaoriNumbers(val numbers: List<MI>) {
    operator fun get(index: Int): MI {
        return numbers[index]
    }
}

Easy. And this is actually a good use of operator overloading I think.

Also note I am using an enum here to restrict the values that my MaoriNumbers object will support:

enum class MaoriNumbersEnum {
    TAHI, RUA, TORU, WHA, RIMA, ONO, WHITU, WARU, IWA, TEKAU
}

This is a call-back to my earlier article "Kotlin: more koans, more random investigation".

---

OK: that's enough. I seem to've got into the swing of things with the writing after about 15min. This is by no means my best article ever, but I think it's readable, and in writing everything thing down it's solidified things in my head a bit better. Cool. Do give me a rark-up if this reads like I'm just going through the motions a bit, it'd be good to know what other ppl think.

Oh yeah! The code! It's here: /src/test/kotlin/junit/language/operators.

Righto.

--
Adam

Monumental cock

G'day:

Because Elon Musk is a monumental cock that no-one at all should be encouraging (other than to fuck off to Mars on one of his rocketships, I guess), I'm gonna do my bit and wind-down my usage of Twitter, in favour of Mastodon. The first manifestation of this is I will not longer be putting a Twitter status up when I release a new blog article. Yeah, I know, this is largely a "shrug" sort of thing for almost everyone (incl. myself), I don't have any illusions to the contrary. But if we all do something small: the accumuled results will be something bigger.

However if you use Twitter as a mechanism to know when I've written something, that'll no longer work. I'm on @adam_cameron on Mastodon. I'll be pinging from there in future.

I'll still ping this article on Twitter, but that's it.

Righto.

--
Adam

CFML: addressing confusion around arrays returned from Java methods and using them with CFML code

G'day:

This has come up often enough that it's probably worth having something clear and googleable around for people to find when this crops up for them.

Context

Sometimes it's useful to call a Java method on a CFML object to benefit from functionality that's in Java that's not in CFML. Being able to call split to split a CFML string on a regular expression pattern is a good example:

string = "abcde"
arrayOfChars = string.split("")
writeDump(arrayOfChars)

Lovely.

Problem

So what's the problem? Often there isn't one. However for people who prefer using CFML's object.method() syntax rather than its function(object) syntax, they might get a surprise:

nextChars = arrayOfChars.map((char) => chr(asc(char) + 1))

This results in:

The map method was not found.
Either there are no methods with the specified method name and argument types
or the map method is overloaded with argument types that ColdFusion cannot decipher reliably.
ColdFusion found 0 methods that match the provided arguments.
If this is a Java object and you verified that the method exists, use the javacast function to reduce ambiguity.

Or Lucee (less info, slightly more helpful as to what the issue is):

No matching Method/Function for [Ljava.lang.String;.map(lucee.runtime.type.Lambda) found

What's the problem? Look at the Lucee error. It's pointing out that arrayOfChars is a [Ljava.lang.String (a Java String[]). So that code is trying to call CFML's map method on a Java String[]. Java String[] doesn't have a map method. one has to recall that when one is using object.method() syntax then the type of the object is what dictates what methods can be called. It's not the same with function(object) when function's implementation can take a "close enough" type and cast it to the type it actually needs.

"Workaround"

It's important to note that this would work no worries:

nextChars = arrayMap(arrayOfChars, (char) => chr(asc(char) + 1))

Solution

However sometimes one might want an actual CFML array (so the object passes type-checks, etc), and this is easy enough to achieve:

arrayOfChars = arrayNew(1).append(arrayOfChars, true)

Here we are creating a CFML array, and then using its append method - which will take a Java array and cast it to a CFML array internally - before appending it to the array it's being called on. Job done. Oh the true argument there just means to append the arrays together, rather than appending the first argument into the last element of the first array. Try it yerself to see the difference: pass it false instead.

Summary / proof

string = "abcde"
arrayOfCharsFromSplit = string.split("")

arrayOfCharsAfterAppend = arrayNew(1).append(arrayOfCharsFromSplit, true)

nextChars = arrayOfCharsAfterAppend.map((char) => chr(asc(char) + 1))

writeDump([
    values = [
        arrayOfCharsFromSplit = arrayOfCharsFromSplit,
        arrayOfCharsAfterAppend = arrayOfCharsAfterAppend,
        nextChars = nextChars
    ], types = [
        arrayOfCharsFromSplit = arrayOfCharsFromSplit.getClass().getName(),
        arrayOfCharsAfterAppend = arrayOfCharsAfterAppend.getClass().getName(),
        nextChars = nextChars.getClass().getName()
    ]
])

And the code is in a trycf.com gist today.

Righto.

--
Adam

Kotlin: more koans, more random investigation

G'day:

I started doing the Kotlin koans a while back, and discuss my meagre progress in these articles:

• Kotlin: an afternoon learning Kotlin stuff
• Kotlin: the next morning learning Kotlin stuff

I used the koans as a jumping off point to look at stuff. My mindset was "OK, I need to do [whatever] to make the koans exercise pass, but what is that all about?" And today I shall continue.

---

TODO

In Kotlin a todo is not just a marker of guilt and a pretence one will come back and finish things later, but an actual function:

@DisplayName("Tests of the TODO function")
class TodoTest {
    @Test
    fun `It should throw a NotImplementedError`() {
        shouldThrow<NotImplementedError> {
            TODO()
        }
    }

    @Test
    fun `It should throw a NotImplementedError with a message`() {
        shouldThrow<NotImplementedError> {
            TODO("This is a message")
        }.message shouldBe "An operation is not implemented: This is a message"
    }

}

I guess this is a better approach than to leave a comment to that effect in the code. Harder to just ignore.

---

enum classes

Enums are summarised well on Wikipedia ("Enumerated type"):

In computer programming, an enumerated type […] is a data type consisting of a set of named values […]. The enumerator names are usually identifiers that behave as constants in the language.

For these tests I'm using some enums I've abstracted out into a separate reference class as I use these Maori terms all the time, so I'm finally getting around to putting them in one place.

enum class MaoriNumbersEnum {
    TAHI, RUA, TORU, WHA, RIMA, ONO, WHITU, WARU, IWA, TEKAU
}

enum class MaoriDaysEnum {
    RĀHINA, RĀTŪ, RĀAPA, RĀPARE, RĀMERE, RĀHOROI, RĀTAPU
}

enum class MaoriColoursByRgbEnum(val rgb: Int) {
    WHERO(0xFF0000),
    KARAKA(0xFFA500),
    KŌWHAI(0xFFFF00),
    KĀKĀRIKI(0x00FF00),
    KIKORANGI(0x0000FF),
    TŪĀURI(0x4B0082),
    PAPURA(0x800080)
}

Tests:

@Test
fun `enum elements have a name`() {
    MaoriNumbersEnum.TAHI.name
    MaoriNumbersEnum.TAHI.name shouldBe "TAHI"
}

@Test
fun `enum elements have an ordinal`() {
    MaoriDaysEnum.RĀAPA.ordinal shouldBe 2
}

@Test
fun `subsequent element are greater than previous elements`() {
    MaoriDaysEnum.RĀAPA shouldBeGreaterThan MaoriDaysEnum.RĀTŪ // Weds > Tues
}

@Test
fun `enum elements can have a value`() {
    MaoriColoursByRgbEnum.KĀKĀRIKI.rgb shouldBe 0x00FF00
}

Pretty self-explanatory I think.

What am I currently using these for? Well in my WordCollections class I have this sort of thing:

class WordCollections {
    companion object {
        enum class MI(val value: String) {
            ONE("tahi"),
            TWO("rua"),
            THREE("toru"),
            FOUR("wha"),
            // …
        }

        val listOfMaoriNumbers = listOf(
            MI.ONE.value,
            MI.TWO.value,
            MI.THREE.value,
            MI.FOUR.value,
            // …
        )
        
        // …
    }
    // …
}

And a test for that listOfMaoriNumbers is:

@Test
fun `It should return a list of Maori numbers`() {
    val numbers = WordCollections.listOfMaoriNumbers
    numbers.size shouldBe  10
    numbers[0] shouldBe "tahi"
    numbers[1] shouldBe "rua"
    numbers[2] shouldBe "toru"
    numbers[3] shouldBe "wha"
    // …
}

All it really means is I have an ordered set of uniform "tokens" that I can use to represent Maori numbers, and anywhere I wanna say "wha", I can use MI.FOUR.value; and MI.FOUR is greater than MI.THREE etc. Obvs it's a contrived usage, but that's the idea. They're sets of ordered constants, basically.

---

when

when is Kotlin's take on switch. It's important to note it can be used as either an expression or a statement. Here's an example of it used as an expression:

@Test
fun `It should return the correct value`() {
    val en = "one"
    val mi = translateNumber(en)
    mi shouldBe "tahi"
}

private fun translateNumber(en: String): String {
    val mi = when (en) {
        "one" -> "tahi"
        "two" -> "rua"
        "three" -> "toru"
        "four" -> "wha"
        else -> throw IllegalArgumentException("Unknown number $en")
    }
    return mi
}

The when construct is assigning a value, so it's an expression.

Also note this error I am causing if I comment out the else:

What does it mean by "be exhaustive"? Here's an example:

@Test
fun `It should return the correct value for a colour`() {
    val mi = MaoriColoursEnum.KĀKĀRIKI
    val en = translateColour(mi)
    en shouldBe "green"
}

private fun translateColour(mi: MaoriColoursEnum): String {
    val en = when (mi) {
        MaoriColoursEnum.WHERO -> "red"
        MaoriColoursEnum.KARAKA -> "orange"
        MaoriColoursEnum.KŌWHAI -> "yellow"
        MaoriColoursEnum.KĀKĀRIKI -> "green"
        MaoriColoursEnum.KIKORANGI -> "blue"
        MaoriColoursEnum.TŪĀURI -> "indigo"
        MaoriColoursEnum.PAPURA -> "violet"
    }
    return en
}

Here I have a case for every single possible value of mi (it has to be one of the colours defined in MaoriColoursEnum), so there is no possibility of an else situation arising.

This shows one of the other benefits of using enum types: it gives control over which values are possible in a situation. I can't specify MaoriColoursEnum.PARAURI (brown), because it's not defined in MaoriColoursEnum. So as well as an enum being a "set" of stuff, it's a bounded set of stuff.

OK, so what's a when statement? It's just when one doesn't assign a value from it. Maybe the cases perform actions rather than derive a value, eg:

@Test
fun `It should print the correct English day for the passed-in Maori day`() {
    val rāmere = MaoriDaysEnum.RĀMERE
    val output = SystemLambda.tapSystemOut {
        printEnglishDayFromMaori(rāmere)
    }
    output shouldBe "Friday"
}

private fun printEnglishDayFromMaori(mi: MaoriDaysEnum) {
    when (mi) {
        MaoriDaysEnum.RĀHINA -> print("Monday")
        MaoriDaysEnum.RĀTŪ -> print("Tuesday")
        MaoriDaysEnum.RĀAPA -> print("Wednesday")
        MaoriDaysEnum.RĀPARE -> print("Thursday")
        MaoriDaysEnum.RĀMERE -> print("Friday")
        MaoriDaysEnum.RĀHOROI -> print("Saturday")
        MaoriDaysEnum.RĀTAPU -> print("Sunday")
    }
}

Here I'm printing, not returning a value. It's a semantic difference, really. At least I could not find any other meaningful difference, from googling about. I only mention it at all because the docs do.

Right. That's the very first koans exercise of the day covered. Next…

---

Sealed classes

Reminder: by default classes in Kotlin are closed by default. The cannot be extended. If one make a class open, then anything can extend it. If one makes a class sealed then one can extend it, but only by subclasses in the same package.

I'm gonna use a sealed interface in this example (because it makes more sense to me), but the same applies to sealed interfaces.

First I have this lot in its own package:

package junit.language.classes.fixtures.package1

sealed interface SomeSealedInterface

class SomeSealedImplementation(val property: String) : SomeSealedInterface {
    fun useThisMethod(): String {
        return property
    }
}

class SomeOtherSealedImplementation(val property: String) : SomeSealedInterface {
    fun useThisOtherMethod(): String {
        return property
    }
}

This is a daft interface & implementation, I know; but bear with me.

@Test
fun `A sealed class does not need an else in a when`() {
    fun handleSomeSealedInterfaceInstance(obj: SomeSealedInterface): String {
        return when (obj) {
            is SomeSealedImplementation -> obj.useThisMethod()
            is SomeOtherSealedImplementation -> obj.useThisOtherMethod()
        }
    }
    val testObj = SomeSealedImplementation("some property value")

    val result = handleSomeSealedInterfaceInstance(testObj)

    result shouldBe "some property value"
}

The key bit here is not so much what I'm testing, it's that the when expression doesn't need an else option. The compiler knows that the only two possible options for a SomeSealedInterface are one of either a SomeSealedImplementation or a SomeOtherSealedImplementation: there can be no other options. If it wasn't a sealed interface, then anything else could implement it, so I'd either need to handle that here, or have an else.

The docs say this, which makes a kind of sense:

In some sense, sealed classes are similar to enum classes: the set of values for an enum type is also restricted, but each enum constant exists only as a single instance, whereas a subclass of a sealed class can have multiple instances, each with its own state.

I checked what happens if I tried to use that sealed interface in a different package:

So… err… that's a long way of saying "nope". Cool.

---

Extension functions

One can bolt new functionality into an existing class:

@Test
fun `an extension function can be called on an instance of a class`() {
    class TranslationPair(val en: String, val mi: String)

    fun TranslationPair.getBoth(): String {
        return "$en $mi"
    }

    val green = TranslationPair("green", "kākāriki")

    val result = green.getBoth()
    result shouldBe "green kākāriki"
}

Here I've added a getBoth method to my TranslationPair.

It seems one can also do this to inbuilt classes:

@Test
fun `an extension function can be added to an inbuilt Kotlin class`() {
    fun String.toMaori(): String {
        return when (this) {
            "one" -> "tahi"
            "two" -> "rua"
            "three" -> "toru"
            "four" -> "wha"
            else -> throw IllegalArgumentException("Unknown number $this")
        }
    }

    val result = "four".toMaori()
    result shouldBe "wha"
}

Here I've added a toMaori method to the String class. I'm gonna file this under "good to know: don't do it".

The docs go to lengths to point out that the extension function is not actually monkeying with the original class, it's all just hocus-pocus in the way the function is called. Fair cop. But for one's implementation code, it looks the same. Handy enough, I think. If used cautiously.

There's also Other Stuff one can do with extension functions - and extension properties - but nothing that I thought I could meaningfully expand on here that the docs don't do a fine job of. Just go RTFM ;-).

---

That's the end of that next section of koans exercises, and I feel like a break from Kotlin, so I'll end here for now.

Code for this article is on GitHub @ Tag 1.17, specifically:

• WordCollections.kt
• TodoTest.kt
• EnumTest.kt
• WhenTest.kt
• SealedClassesTest.kt
• Package1.kt
• ExtensionFunctionsTest.kt

Righto.

--
Adam

Kotlin / Ktor: G'day world from a Docker container

G'day:

Not sure what this article is going to end up being about. However I am hovering over the "New Project" button in IntelliJ, and am gonna attempt to at least get to a "G'day world" sort of situation with a Ktor-driven web service today.

Why Ktor

We need to port our monolithic CFML/CFWheels app to a more… erm… forward-thinking and well-designed solution. The existing app got us to where we are, and pays our salaries, but its design reflects a very "CFML-dev" approach to application design. We've decided to shift to Kotlin, as you know. We also need to adopt some sort of framework to implement the application atop-of, and we've chosen Ktor for a few reasons:

• It's focus is micro-services and small footprint.
• From what I've read, it focuses on being a framework instead of being an opinion-mill, how other frameworks can tend to be.
• It's written for Kotlin; unlike say Spring, which is written for Java and it shows. We're using Kotlin to have the benefits of the JVM, but to steer clear the Java Way™ of doing things.
• It's created by JetBrains, who created Kotlin, so hopefully the Ktor design team with be aligned with the Kotlin design team, so it should be a pretty Kotlin-idiomatic way of doing things.
• Support for it is baked-in to IntelliJ, so it's a "first class citizen" in the IDE.

Also basically we need to pick something, so we're cracking on with it. If we do some quick investigation and it turns our Ktor ain't for us: I'd rather know sooner rather than later.

Let's get on with it.

---

Project

One can create a new Ktor project via IntelliJ ("New Project"):

I've only filled in the situation-specific stuff here, and left everything else as default. I've clicked the "Create Git repository" option: I hope if gives me the option to provide a name for it before it charges off and does it, cos I don't want it just to be called "gdayworld". So I might back out of that choice if it doesn't work for me:

Let's press "Next"…

Argh! I have to make decisions! I haven't even finished my first coffee of the day yet!

There are roughly one million plug-ins on offer here, and I don't even know what most of them are. For now, all I need this thing to do is to have testing for a greeting endpoint that says "G'day world" or something, so I doubt I'll need most of this stuff. Let's have a scan through.

OK, I've selected these ones:

• Routing
• DefaultHeaders
• CallLogging
• CallId
• kotlinx.serialization - this also required the ContentNegotiation plug-in

After clicking "create" it got on with it, downloaded some stuff, built the project and declared everything was fine. I now have this lot:

---

Baseline checks

Right, let's see what tests it installed by default:

package me.adamcameron

import io.ktor.server.routing.*
import io.ktor.http.*
import io.ktor.server.plugins.callloging.*
import org.slf4j.event.*
import io.ktor.server.request.*
import io.ktor.server.plugins.callid.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlin.test.*
import io.ktor.server.testing.*
import me.adamcameron.plugins.*

class ApplicationTest {
    @Test
    fun testRoot() = testApplication {
        application {
            configureRouting()
        }
        client.get("/").apply {
            assertEquals(HttpStatusCode.OK, status)
            assertEquals("Hello World!", bodyAsText())
        }
    }
}

Most of those imports aren't necessary btw, that's a wee bit sloppy. It only claims to need these ones:

import io.ktor.http.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlin.test.*
import io.ktor.server.testing.*
import me.adamcameron.plugins.*

I'll leave it as-is for now. The test looks sound actually. Well: I've purposely not looked at the code yet, but a test that tests that a GET to / returns "Hello World!" seems reasonable. Let's run it:

Cool. OK, let's run the app then, given it looks like it'll work:

C:\Users\camer\.jdks\semeru-11.0.17\bin\java.exe […]
2022-10-16 11:01:49.119 [main]  INFO  ktor.application - Autoreload is disabled because the development mode is off.
2022-10-16 11:01:49.205 [main]  INFO  ktor.application - Application started in 0.148 seconds.
2022-10-16 11:01:49.205 [main]  INFO  ktor.application - Application started: io.ktor.server.application.Application@57312fcd
2022-10-16 11:01:50.448 [DefaultDispatcher-worker-1]  INFO  ktor.application - Responding at http://127.0.0.1:8080  

It ran. Does it actually respond on http://127.0.0.1:8080?

Cool. OK, so I have a test that passes an an app that works. Gonna push that to GitHub as v0.2 (v0.1 was the empty repo). And I'm gonna have a shufti around the files it's created and see what's what.

---

Tweaking

OK, I'm not gonna look at those old-school xUnit-style tests. I'm gonna adapt them to use the more declarative BDD style I've been using so far when testing stuff with Kotlin. So this means I'm going to add some Kotest dependencies. The test is now:

@DisplayName("Tests of the / route")
class ApplicationTest {
    @Test
    fun `Tests the root route responds with the correct status and message`() = testApplication {
        application {
            configureRouting()
        }
        client.get("/").apply {
            status shouldBe HttpStatusCode.OK
            bodyAsText() shouldBe "Hello World!"
        }
    }
}

I'm also refactoring the class name and location to src/test/kotlin/acceptance/IndexRouteTest.kt. It's not testring the app, it's testing the route. Plus it's an acceptance test, and I wanna keep those separate from unit tests / integration tests etc (poss premature optimisation here I guess). I've also lost the subdirectory structure from /src/main/kotlin/me/adamcameron/Application.kt to be just /src/main/kotlin/Application.kt. Kotlin's own style guide recommends this:

In pure Kotlin projects, the recommended directory structure follows the package structure with the common root package omitted. For example, if all the code in the project is in the org.example.kotlin package and its subpackages, files with the org.example.kotlin package should be placed directly under the source root, and files in org.example.kotlin.network.socket should be in the network/socket subdirectory of the source root.

Next I feel there's a design bug in the index route, but I'm gonna push my current tweaks first, and sort that out in the next section.

---

Giving control to a controller

This design bug: here's the entirety of the implementation of that index route and its handling:

fun Application.configureRouting() {

    routing {
        get("/") {
            call.respondText("Hello World!")
        }
    }
}

That's in /src/main/kotlin/plugins/Routing.kt

Routing should limit itself to what it says ion the tin: routing. It should not be providing the response. It should route the request to a controller which should control how the response is handled. I know this is only example code, but example could should still follow appropriate design practices. So erm: now I have to work out how to create a controller in Ktor. I'm pleased I have a green test on that index route though, cos this is all pretty much a refactoring exercise, so whatever I do: in the end I'll know I have done good if the test still passes.

Hrm. Having not found any examples in the Ktor docs of how to extract controller code out of the routing class, I found myself reading Application structure, specifically these paras:

Different to many other server-side frameworks, it doesn't force us into a specific pattern such as having to place all cohesive routes in a single class name CustomerController for instance. While it is certainly possible, it's not required.

Frameworks such as ASP.NET MVC or Ruby on Rails, have the concept of structuring applications using three folders - Model, View, and Controllers (Routes).

My emphasis. I see. Ktor does not separate-out the idea of routing from the idea of controllers, I see. To me they're different things, but I guess I can see there's overlap. I'm not hugely enamoured with their thinking that "despite the rest of the world using the term MVC, we know better: we're gonna think of it as MVR". Just… why. If you wanna conflate routing and controllers, yeah fine. But in that case they conflate into the controller part of MVC. You don't just go "ah nah it's MVR, trust me". Remember what I said before about opinionated frameworks? This is why I don't like it when frameworks have opinions.

But anyway.

We can still separate out groups of "route-handlers" (sigh) into separate functions. ow I have this:

package routes

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Route.indexRouting() {
    route("/") {
        get {
            call.respondText("Hello World!")
        }
    }
}

And my original configureRouting function is just this:

fun Application.configureRouting() {

    routing {
        indexRouting()
    }
}

That's good enough.

---

Auto-reload

One good thing my RTFMing about controllers lead me to was how to get my app to rebuild / reload when I make code changes. By default every time I changed my code I had to shut down the app (remember it's serving a web app now), rebuild, and then re-run the app. That was not the end of the world, but was pretty manual.

Ktor have thought about this, and the solution is easy.

First, I tell my app it's in development mode (in gradle.properties):

junitJupiterVersion=5.9.0
kotestVersion=5.5.0
kotlinVersion=1.7.20
ktorVersion=2.1.2
logbackVersion=1.2.11

kotlin.code.style=official

org.gradle.warning.mode=all

development=true

This in turn is picked up by code in build.gradle.kts

application {
    mainClass.set("ApplicationKt")

    val isDevelopment: Boolean = project.ext.has("development")
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")
}

(that code was already there).

Then I needed to tell the app what to pay attention to for reloading (in Application.kt):

fun main() {
    embeddedServer(Netty, port = 8080, host = "0.0.0.0", watchPaths = listOf("classes")) {
        configureMonitoring()
        configureSerialization()
        configureRouting()
    }.start(wait = true)
}

classes there is a reference to build/classes in the project file system.

Then get Gradle to rebuild when any source code changes:

PS C:\src\kotlin\ktor\gdayworld> ./gradlew --continuous :build
BUILD SUCCESSFUL in 1s
13 actionable tasks: 13 up-to-date

Waiting for changes to input files... (ctrl-d then enter to exit)
<-------------> 0% WAITING
> IDLE

And another instance of Gradle to run the app with it watching the build results:

PS C:\src\kotlin\ktor\gdayworld> ./gradlew :run                  
> Task :run
2022-10-16 14:21:19.374 [main]  DEBUG ktor.application - Java Home: C:\apps\openjdk\EclipseAdoptium
2022-10-16 14:21:19.374 [main]  DEBUG ktor.application - Class Loader: jdk.internal.loader.ClassLoaders$AppClassLoader@73d16e93:...]
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\me\adamcameron\plugins for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\routes for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\me for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\META-INF for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\me\adamcameron for changes.
2022-10-16 14:21:19.390 [main]  DEBUG ktor.application - Watching C:\src\kotlin\ktor\gdayworld\build\classes\kotlin\main\plugins for changes.
2022-10-16 14:21:19.562 [main]  INFO  ktor.application - Application started in 0.298 seconds.
2022-10-16 14:21:19.562 [main]  INFO  ktor.application - Application started: io.ktor.server.application.Application@5a45133e
2022-10-16 14:21:19.937 [main]  INFO  ktor.application - Responding at http://127.0.0.1:8080
<===========--> 85% EXECUTING [15s]
> :run

When I change any source code now, the project rebuilds, and the app notices the recompiled classes, and restarts itself:

modified: C:\src\kotlin\ktor\gdayworld\src\main\kotlin\routes\IndexRoutes.kt
Change detected, executing build...


BUILD SUCCESSFUL in 6s
13 actionable tasks: 12 executed, 1 up-to-date

Waiting for changes to input files... (ctrl-d then enter to exit)
<=============> 100% EXECUTING [8m 55s]

2022-10-16 14:26:20.438 [eventLoopGroupProxy-4-2]  INFO  ktor.application - 200 OK: GET - /
2022-10-16 14:26:34.861 [eventLoopGroupProxy-3-1]  INFO  ktor.application - Changes in application detected.
2022-10-16 14:26:35.073 [eventLoopGroupProxy-3-1]  DEBUG ktor.application - Changes to 18 files caused application restart.
[...]
2022-10-16 14:26:35.106 [eventLoopGroupProxy-3-1]  INFO  ktor.application - Application auto-reloaded in 0.012 seconds.
2022-10-16 14:26:35.106 [eventLoopGroupProxy-3-1]  INFO  ktor.application - Application started: io.ktor.server.application.Application@33747fec
2022-10-16 14:26:35.107 [eventLoopGroupProxy-4-2]  INFO  ktor.application - 200 OK: GET - /
<===========--> 85% EXECUTING [5m 32s]
> :run

Note how the app doesn't restart until I actually use it, which is good thinking.

One might as why I have dropped down to a shell to do this autoload stuff? As far as I can tell it's not baked into IntelliJ yet, so needs to be handled directly by Gradle for now. It's not a hardship. I mean: the shells I am running there are being run from within IntelliJ, it's just slightly more complicated than a key-combo or some mouseclicks.

OK. That's all good progress. I'm gonna take a break and come back and create my own controller / response / etc, which is what the object of the exercise was today.

---

Docker

Ktor's way

I was not expecting this to be the next step, but I just spotted some stuff about Docker in the Ktor docs ("Docker"), so I decided to see what they said.

[time passes whilst I do battle with the docs]

OK, screw that. It's a very perfunctory handling of it. I can build a jar and create an image that will run it, and then run the container - and it all works - but it's… a bit… "proof of concept". From reading the docs and the code snippets that link from the docs (Deployment - Ktor plugin › Build and run a Docker image).

I had to add this to my build.gradle.kts file:

ktor {
    fatJar {
        archiveFileName.set("gday-world-ktor.jar")
    }
    docker {
        jreVersion.set(io.ktor.plugin.features.JreVersion.JRE_17)
        localImageName.set("gday-world-ktor")
        imageTag.set("${project.version}-preview")
        portMappings.set(listOf(
            io.ktor.plugin.features.DockerPortMapping(
                8080,
                8080,
                io.ktor.plugin.features.DockerPortMappingProtocol.TCP
            )
        ))
    }
}

And then from the shell I could run this lot:

PS C:\src\kotlin\ktor\gdayworld> ./gradlew :buildFatJar     
[…]
PS C:\src\kotlin\ktor\gdayworld> ./gradlew :runDocker

And I would indeed end up with a running Docker container. Which is handy, but I had no control over what params were passed to docker run, so I couldn't even give the container a name, so I just ended up with one of Docker's random ones. That's a bit amateurish. I checked to see if I was missing anything with the plugin, but this is the code (from Ktor's repo on GitHub):

private abstract class RunDockerTask : DefaultTask() {
    @get:Inject
    abstract val execOperations: ExecOperations

    @get:Input
    abstract val fullImageName: Property<String>

    @TaskAction
    fun execute() {
        val dockerExtension = project.getKtorExtension<DockerExtension>()
        execOperations.exec {
            it.commandLine(buildList {
                add("docker")
                add("run")
                for (portMapping in dockerExtension.portMappings.get()) {
                    add("-p")
                    with(portMapping) {
                        add("${outsideDocker}:${insideDocker}/${protocol.name.lowercase()}")
                    }
                }
                add(fullImageName.get())
            })
        }
    }
}

It looks to me like it simply builds a string docker run [port mappings] [image name], and that's it. No scope for me to specify any other of docker run's parameters in my build config.

So: nah, not doing that; I'll DIY. It's at least shown me what I need to do in a DockerFile and I can organise my own docker-compose.yml file.

---

My way

[…]

I have this docker/Dockerfile:

FROM gradle:7-jdk17 AS build
COPY --chown=gradle:gradle .. /home/gradle/src
WORKDIR /home/gradle/src
RUN gradle test --no-daemon
RUN gradle buildFatJar --no-daemon

FROM openjdk:17
EXPOSE 8080:8080
RUN mkdir /app
COPY --from=build /home/gradle/src/build/libs/*.jar /app/gday-world-ktor.jar
ENTRYPOINT ["java","-jar","/app/gday-world-ktor.jar"]

This is pretty much lifted from the Ktor Docker › Prepare Docker image docs I linked to above, I've just added the test-round in first.

And this docker/docker-compose.yml:

version: '3'

services:
  gday-world-ktor:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    ports:
      - "8080:8080"
    stdin_open: true
    tty: true

And when I run docker-compose up --build --detach, after a couple of minutes, I get an up and running container with my app in it. Bonus: it halts if my tests don't first pass.

I'm not enamoured with the "after a couple of minutes" part of this: seems really slow for what it needs to do. I am "sure" there must be a way of telling Gradle to do the build, test-run and jar-build all on one operation. However I'm over googling things starting with "gradle" today, so I'm gonna leave it for now.

I'm pretty happy with the progress I made today.

Righto.

--
Adam