DEV Community: Alexander Nozik

Keep listening or do your job and finish

Alexander Nozik — Sun, 30 Jun 2024 09:58:09 +0000

People talk a lot about so-called design patterns (usually referencing those made in the famous book for C++). Though those patterns themselves are not universal, they change from language to language and their usage strongly depends on the specific task at hand. However, there are several among them that are more frequently used. One of those is the listener/observer pattern, which implies that an object is allowed to attach a listener object to it to observe its changes or other events.

In Kotlin syntax a general API for using a listener looks like this:

interface Observable {

    fun addListener(owner: Any?, listener: (Event) -> Unit)

    fun removeListener(owner: Any?)
}

The first method of this interface is quite obvious and familiar. listener is the callback which is used when something interesting happens in the Observable. The Event could be different and even could have several arguments instead of one. The thing people tend to forget about is the second argument: owner. It becomes important when we remember that listeners need not only to be added but removed as well. When you remove a listener, you need to specify which listener to remove. So, you either need to return a removal handler from an addListener method or provide an identity to the removed object. Sometimes people try to use the listener itself to provide listener identity like this: fun removeListener(listener: (Event) -> Unit). But doing this is most probably a mistake because lambda functions identity is a tricky thing and at some point, it could produce unexpected results. Furthermore, one needs to store this function somewhere in case it needs to be removed. It is much better to use the owner of the listener (an object, that has an identity) as a handle. As an additional benefit, one could remove all listeners from the same handle or even use a null handle to remove all listeners.

Even with the handle identity problem solved, there is a problem of "hanging" listeners. In a dynamic structure, it is quite easy to forget to "detach" the listener that points to removed objects. It leads to a memory leak because the referenced object still exists in the listener so it could not be collected by GC.

The way to solve this problem is inspired by Kotlin SharedFlow. It attaches a listener on each subscription and removes said listener automatically when the subscription flow is canceled or collected. This way, you do not need to think about removing the listener manually. You just stop listening.

Let us see, how we can do that in a "flowless" environment:

interface AutoDetachObservable {
    fun listen(
        scope: CoroutineScope, 
        listener: (Event) -> Unit
    ): Job
}

The scope provides a CoroutineScope in which the listener runs. When it is canceled, the listener (and all other listeners in the scope) is automatically detached. And the resulting Job could be canceled manually thus canceling only this subscription. This way the construct has not one, but two levels of control for subscription cancelation.

The implementation of this mechanism could look like this:

fun listen(
    scope: CoroutineScope, 
    listener: (Event) -> Unit
): Job{
    val id = generateUniqueId()
    val job = scope.launch{ 
        listenerRegistry[id] = listener 
        while(isActive){
            delay(1000) //cancelation will break delay anyway
            // just keep job active 
        }
    }
    job.invokeOnCompletion{ listenerRegistry.remove(id) }
    return job
}

There was a mistake in the initial example Thanks @nicopicodev for noticing it. In order to make job running indefinitely one needs to add something for it to do. To avoid it one could use only the external scope, without additional job.

This way the removal of the listener will be triggered both on scope cancelation and on Job cancelation. The id is a simple internal implementation detail that ensures that internal listeners can be removed. It is attached to a specific job, so it needs not to be exposed to the external user.

An additional benefit of said approach is that there is a CoroutineScope provided, so with some additional changes, it is possible to make listener a suspended function and run it in the context of a listener, not in the target object. Making listeners suspended is quite useful in concurrent systems to avoid data races for events.

After I wrote the post, I found out that I've already written a related one two years ago: https://dev.to/altavir/to-flow-or-not-to-flow-message-subscription-in-kotlin-57ea.

The cover image is taken from "Большой Ух" cartoon.

When encapsulation is a trouble...

Alexander Nozik — Mon, 06 Mar 2023 13:48:29 +0000

I have not written anything for a long time, but I just encountered a problem, which I see quite frequently in API design so I can't pass it. So I will write a cer

I am doing an interface in Compose Desktop and I need to create a context menu that appears near the cursor. Compose Desktop has a neat component called CursorDropdownMenu for this.

The problem is that it captures the cursor position relative to the window borders. So when the window gets resized, the popup appears in the wrong position. OK, no problems here, I will just take the source code and create my variation of the component, which uses external coordinates. Here is the code:

@Composable
fun CursorDropdownMenu(
    expanded: Boolean,
    onDismissRequest: () -> Unit,
    focusable: Boolean = true,
    modifier: Modifier = Modifier,
    content: @Composable ColumnScope.() -> Unit
) {
    val expandedStates = remember { MutableTransitionState(false) }
    expandedStates.targetState = expanded

    if (expandedStates.currentState || expandedStates.targetState) {
        val transformOriginState = remember { mutableStateOf(TransformOrigin.Center) }

        var focusManager: FocusManager? by mutableStateOf(null)
        var inputModeManager: InputModeManager? by mutableStateOf(null)

        Popup(
            focusable = focusable,
            onDismissRequest = onDismissRequest,
            popupPositionProvider = rememberCursorPositionProvider(),
            onKeyEvent = {
                handlePopupOnKeyEvent(it, onDismissRequest, focusManager!!, inputModeManager!!)
            },
        ) {
            focusManager = LocalFocusManager.current
            inputModeManager = LocalInputModeManager.current

            DropdownMenuContent(
                expandedStates = expandedStates,
                transformOriginState = transformOriginState,
                modifier = modifier,
                content = content
            )
        }
    }
}

It seems like the only thing I need is to take the Popup part and just replace the popupPositionProvider. But I am not that lucky. See, the handlePopupOnKeyEvent, which holds the logic to evaluate closing the popup on clicks outside, is private.

@ExperimentalComposeUiApi
private fun handlePopupOnKeyEvent(
    keyEvent: androidx.compose.ui.input.key.KeyEvent,
    onDismissRequest: () -> Unit,
    focusManager: FocusManager,
    inputModeManager: InputModeManager
): Boolean

This logic is not exposed directly to the library consumer so the developers decided to make it private. On practice, it means that anyone, who wants to slightly change the behavior, needs to fully replicate parts of a library. In this particular case, the logic is not very large, but I know cases, where a library user needs to replicate a significant part of a library codebase to change the behavior.

The major question is if encapsulation is justified in this case. No, it is not. It does not hide the implementation detail, instead, it hides the logic that is used by default. One should not leave functions like this hanging in the top-level scope because of the namespace pollution, but in Kotlin it is quite easy to avoid it. Just use extensions or a companion object of a nearby type and the method will be accessible without polluting the namespace.

The moral of this short story is that encapsulation is not always a good thing. One should hide a logic that is purely implementation detail, but one should not hide the logic, that is important for alternative implementations. A good recommendation on how to decide what needs to be public is to try to imagine what will happen if you need to implement the same logic with one slight change. If you need private APIs for it, you probably need to change something.

To Flow or not to Flow? Message subscription in Kotlin.

Alexander Nozik — Fri, 12 Aug 2022 10:31:49 +0000

In this short article I want to discuss to different patterns of doing reaction subscriptions in Kotlin via callbacks and via Flow.

Let's assume that you have some kind of object or structure and you want to observe changes done to this structure.

The classic way to this is the following:

fun MyStructure.onChange(block: MyStructure.(Key) -> Unit)

and then use it like this:

myStructure.onChange{ key ->
  println(get(key))
}

I've intentionally done it using Kotlin receiver feature because it makes the classic layout even more neat. You pass not only the change place, but also a reference to a changed object so you can use pre-defined block function.

Now let's see how it looks using Kotlin coroutines Flow API:

val MyStructure.changes: Flow<Key>

myStructure.changes.onEach{ key ->
  println(myStructure.get(key)
}.launchIn(scope)

It seems like Flow is much harder to use. Also it requires a CoroutineScope to be used. And since you should not use GlobalScope for this, you need to think about the scope lifecycle.

I do not want to talk about performance issues here. If you have so many subscribers, it is a performance problem, you need to solve this problem elsewhere, but Flow overhead is probably larger as well.

On the other hand, you can easily do transformations with events from Flow. Like this:

myStructure.changes
  .filter{ key -> key.startsWith("my")}
  .map{ key -> myStructure.get(key)}
  .onEach{ value -> println(value)}
  .launchIn(scope)

But there is a problem people frequently forget about

If you make a subscription, you probably want to unsubscribe as well. Otherwise it leads to memory leaks (in VM sense) - some objects avoiding garbage collections because somebody holds their subscription handle.

So you write a code like this:

fun MyStructure.onChange(block: MyStructure.(Key) -> Unit)
fun MyStructure.removeChangeListener(block: MyStructure.(Key) -> Unit)

Actually, please do not write a code like this. Because in this case you rely on function equality to remove the correct listener and function equality is not reliable. Moreover, you will not be able to create a function via lambda like I've done above. You need to create it separately and store somewhere.

I usually do it this way:

fun MyStructure.onChange(owner: Any, block: MyStructure.(Key) -> Unit)
fun MyStructure.removeChangeListener(owner: Any)

In this case, I use the owner object to check equality of a callback holder. If a single owner holds several callbacks, all of them will be removed and it has its uses. The only problem now is not to forget to remove the listener when it is no longer used (and it means that you need to think about lifetimes like in case of Flow).

The Flow does not require specific unsubscription methods. Usually if you stop consuming the Flow, it is not used anymore. Also you can manually unsubscribe from it by canceling the subscription job:

val job = myStructure.changes.onEach{ key ->
  println(myStructure.get(key)
}.launchIn(scope)

job.cancel()

Due to structured concurrency, you usually do not need to think about canceling the job manually. When the external scope is closed, all child jobs are canceled automatically. So the lifetime management is automatic.

Still, you need to manage the lifetime via coroutine scope (which is quite convenient).

Both ways are valid and I can't say that one of them should be always used instead of the other. I think I would prefer the Flow way for complex systems because there is not risk of forgetting to unsubscribe. But in some cases you do not want to bother with scopes.

Cover image photo by Chris Stenger on Unsplash

My first Space service

Alexander Nozik — Wed, 27 Apr 2022 07:55:35 +0000

Anyone needs to do new things from time to time. Today I decided to do two new things simultaneously. Write my first article to DEV.to and make official my first Space application.

TL;DR - go for the code: https://github.com/altavir/space-document-extractor

Motivation

JetBrains Space is a relatively new fast-growing all-in-one solution for intranet/team workspace. We've been using it in our team since the first preview announcement in 2019 (I was in KotlinConf when it was announced and got pretty excited). Right now we are moving most of our work from Slack/Confluence/GitHub stack into Space with GitHub mirror.

For our team, the knowledge base is very important and we were looking forward to using it in Space. We stopped using Confluence, but there are no full-fledged alternatives. We started using the knowledge base in YouTrack, which is not bad, but it still somehow kills the purpose of the all-in-one tool.

Recently, the knowledge base ( Documents ) in Space reach the next stage of its evolution and finally became ready for use. We started to write technical documentation and notes there. But found, that we need a way to get it from Space somehow.

Currently, Space does not provide a way to just download a directory (I think the feature is worth adding), so I decided to create an application to do that using Space API.

Implementation

The code is available in the repo. You can start with it.

The Space SDK is still pretty unstable and has some bugs, but it is quite easy to use and much more intuitive, than, say, Google Cloud. I will try to walk you through it.

Stage 1. Creating application

First, you need to create a Space application to provide access to API. Go to Administration -> Applications and create a new one. You need to set up permissions like it is shown here. It is not always obvious which permissions you need and error messages are sometimes misleading. For example, I spent some time wondering why I get a zero response for a correct request only to find out, that I need to manually add permissions to restricted projects. But I think they will clean it in the future.

The authentication is always the hardest thing, so I went with the default way (using just the client Id and a secret), but it proved to be surprisingly easy.
.

You can try the APIs in the playground in the same section and get some insight into how they work.

Stage 2. Set up the project with Space SDK.

Just take my build file as a reference.

repositories {
    mavenCentral()
    maven("https://maven.pkg.jetbrains.space/public/p/space/maven")
}

val ktorVersion = "1.6.4"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-auth:$ktorVersion")
    implementation("org.jetbrains.kotlinx:kotlinx-cli:0.3.4")
    implementation("org.jetbrains:space-sdk-jvm:98244-beta")
    implementation("ch.qos.logback:logback-classic:1.2.10")
    testImplementation(kotlin("test"))
}

Be sure to use the correct Ktor version. For me 2.0.0 did not work since SDK has a dependency on it.

You don't need anything else.

Stage 3. Setting up the connection.

It is surprisingly easy:

    val space: SpaceClient = SpaceClient(
        ktorClientForSpace(CIO),
        SpaceAppInstance(
            clientId ?: System.getProperty("space.clientId"),
            clientSecret ?: System.getProperty("space.clientSecret"),
            spaceUrl
        ),
        SpaceAuth.ClientCredentials()
    )

Stage 4. Doing logic.

The whole logic is in this file. You can see there are no new classes (look, Ma, I am a functional programmer!).

The SDK is intuitive and follows the API logic. So you just take a client and see methods and properties that are available. Like this:

projects.documents.folders.subfolders.listSubfolders(projectId, folderId)

Sometimes it does not work as expected, so you have to experiment. For example I had to do this:

    val documents = projects.documents.folders.documents.listDocumentsInFolder(projectId, folderId) {
        id()
    }
    documents.data.forEach {
        val document = projects.documents.getDocument(projectId, it.id) {
            id()
            title()
            documentBody()
            bodyType()
        }
        downloadDocument(directory, document)
    }

because listDocumentsInFolder returns documents without bodies (it is rational, but not obvious from API).

Stage 5. A hacky part.

The document download went rather smoothly. But no we have markdown documents with attachment links that are:

relative,
point to the internet files that require authentication.

In order to fix that, we need to download those images and replace links by local file references.

Currently, Space does not provide API to download files (or at least I did not find it), so I had to do a little bit of reverse engineering.

I checked the requests that are used to access images and found out that they have an additional authorization header Bearer. The same one, the Space client uses to access pages:

So all I need to download images is to manually construct the request:

    val response = ktorClient.request<HttpResponse> {
        url("${server.serverUrl}/d/$imageId")
        method = HttpMethod.Get
        header(HttpHeaders.Authorization, "Bearer ${token().accessToken}")
    }

It is a hack and the actual placement of files could change in the future, but it works for now.

All that is left is to find image references and replace them with text in downloaded markdown files.

That's all.

Conclussion

I hope you will enjoy playing with Space API and I hope there will be a lot of new plugins and applications to enrich the ecosystem. I enjoyed it. Especially in comparison with older heavyweight systems. Kotlin SDK simplifies things a lot.

A bonus

Since we needed not only to download the documents but also to create a report from them, here is the simple PowerShell script to combine documents into a report, using PanDoc: