4. Creating and configuring a client

When repositories and dependencies are configured, we can create instance of Halcyon:

import tigase.halcyon.core.builder.createHalcyon

val halcyon = createHalcyon {
}

4.1. Authentication

Of course, it requires a bit of configuration: to connect to XMPP Server, client requires username and password:

import tigase.halcyon.core.builder.createHalcyon
import tigase.halcyon.core.xmpp.toBareJID

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

4.2. Registering new account

To register new account on XMPP server you need separate instance of Halcyon, configured exactly for this purpose.

import tigase.halcyon.core.builder.createHalcyon

val halcyon = createHalcyon {
    register {
        domain = "xmppserver.com"
        registrationFormHandler { form ->
            form.getFieldByVar("username")!!.fieldValue = "username"
            form.getFieldByVar("password")!!.fieldValue = "password"
        }
    }
}

Note

The server may provide a different set of fields and it is the developer’s responsibility to handle them.

4.3. Connectors

Halcyon library is able to use many connection methods, depends on platform. By default JVM and Android uses Socket and JavaScript uses WebSocket connector.

4.3.1. JVM SocketConnector

In Socket Connector you may configure own DNS resolver, set custom host and port, and define trust manager to check SSL server certificates.

import tigase.halcyon.core.builder.createHalcyon
import tigase.halcyon.core.builder.socketConnector

val halcyon = createHalcyon {
    socketConnector {
        dnsResolver = CustomDNSResolver()
        hostname = "127.0.0.1"
        port = 15222
        trustManager = MyTrustManager()
    }
}

Warning

Note that by default Halcyon doesn’t check SSL server certificates at all!

Halcyon provides two TLS processors: default one, using built-in JSSE and the second using BouncyCastle. The only reason and difference between them is fact that JSSE doesn’t provides a way to get Channel Binding data to use in SASL SCRAM (see SaslModule & Sasl2Module) authentication protocol.

If you want to use BouncyCastle, you have to import tigase.halcyon:halcyon-bouncycastle to your project, and add BouncyCastleTLSProcessor to configuration of connector:

import tigase.halcyon.core.builder.createHalcyon
import tigase.halcyon.core.builder.socketConnector
import tigase.halcyon.core.connector.socket.BouncyCastleTLSProcessor

val halcyon = createHalcyon {
    socketConnector {
        dnsResolver = CustomDNSResolver()
        hostname = "127.0.0.1"
        port = 15222
        trustManager = MyTrustManager()
        tlsProcessorFactory = BouncyCastleTLSProcessor
   }
}

4.3.2. JavaScript WebSocketConnector

If your target platform is JavaScript, then default connector will use WebSocket.

import tigase.halcyon.core.builder.createHalcyon
import tigase.halcyon.core.builder.webSocketConnector

val halcyon = createHalcyon {
    webSocketConnector {
        webSocketUrl = "ws://127.0.0.1:5290/"
    }
}

WebSocket connector has only one configuration parameter: server URL.

4.4. Starting and stopping

Now we are ready to connect client to the XMPP server:

halcyon.connectAndWait()
halcyon.disconnect()

Method connectAndWait() is JVM only method, it esteblish connection in blocking way. To start connection in async mode you have to use connect() method. If library was configured to register new account, thise method will start registration process. Method disconnect() terminates XMPP session, closes streams and sockets.

4.5. Connection status

We can listen for changing status of connection:

halcyon.eventBus.register(HalcyonStateChangeEvent) { stateChangeEvent ->
    println("Halcyon state: ${stateChangeEvent.oldState}->${stateChangeEvent.newState}")
}

Available states:

• Connecting - this state means, that method connect() was called, and connection to server is in progress.

• Connected - connection is fully established.

• Disconnecting - connection is closing because of error or manual disconnecting.

• Disconnected - Halcyon is disconnected from XMPP server, but it is still active. It may start reconnecting to server automatically.

• Stopped - Halcyon is turned off (not active).