3. Five Minutes Client

Lets see how to build Echo Bot with Halcyon library.

3.1. Setting up project

We will use Gradle to build project. First of all we have to add URLs of Maven repositories (see: Setting up a client) to build.gradle.kts

repositories {
    mavenCentral()
    maven("https://maven-repo.tigase.org/repository/release/")
    maven("https://maven-repo.tigase.org/repository/snapshot/")
}

and Halcyon library to dependencies section:

dependencies {
    implementation("tigase.halcyon:halcyon-core:1.0.0")
}

3.2. Halcyon configuration

Creating Halcyon instance and its basic configuration is very simple.

val halcyon = createHalcyon {
    auth {
        userJID = "[email protected]".toBareJID()
        password { "secretpassword" }
    }
}
halcyon.connectAndWait()

Function connectAndWait() is available only in JVM and provides synchronous connection. Default function connect() is asynchronous.

3.3. Sending messages to recipient

Messages are one of the basic types of stanzas sent on the XMPP network. You don’t need to to use any module just to send stanza, you can do that directly from main Halcyon.

val requestBuilder = halcyon.request.message {
    to = "[email protected]".toJID()
    body = "Test message"
}
requestBuilder.send()

As you can see, halcyon.request.message doesn’t send message directly. Instead of that it prepares RequestBuilder, what allows to add some listeners (like onSend) to the builder.

3.4. Listening for incoming messages

All events (receiving message also generates an event) are distributed among listeners by EventBus. To handle received message, you need to register events listener:

halcyon.eventBus.register(MessageReceivedEvent) {
}

Note, that some messages exchanged between client and server may not contain any text, as they are a kind of signals informing the client (or server) about something. That’s why we need to check if incoming message contains body:

halcyon.eventBus.register(MessageReceivedEvent) {
    if (!it.stanza.body.isNullOrEmpty()) {
    }
}

Then we can send back received text:

halcyon.eventBus.register(MessageReceivedEvent) {
    if (!it.stanza.body.isNullOrEmpty()) {
        halcyon.request.message {
            to = it.fromJID
            body = "Echo: ${it.stanza.body}"
        }.send()
    }
}

3.5. Keep application running

Because this is a very simple application and Halcyon does not maintain any threads after the application terminates, we need to prevent the application from terminating when Halcyon is connected. We can add loop to cyclic check Halcyon connection status:

while (halcyon.state == AbstractHalcyon.State.Connected) Thread.sleep(1000)

3.6. Disconnecting bot remotely

Last thing we should add is feature to disconnect and terminate our application remotely. We can add code to existing handler of incoming messages, or we can add another one:

halcyon.eventBus.register(MessageReceivedEvent) {
    if (it.stanza.body == "/stop") {
        halcyon.disconnect()
    }
}

Note, that there is no sender authorization, so anyone is able to terminate the bot.

3.7. Summary

That’s all. We just created very simple bot. As you can see using XMPP network is very easy and (as usual) the most complicated part will be business logic of application.