Two documents for the new event API

doc_snippets.md

These code snippets will replace the existing snippets on the documentation pages

• https://getstream.io/chat/docs/event_listening/?language=kotlin
• https://getstream.io/chat/docs/event_listening/?language=java

---

Specific events

Disposable disposable = client.subscribeForSingle(NewMessageEvent.class,
        (NewMessageEvent event) -> {
            // use event.getMessage()
            return Unit.INSTANCE;
        });
        
// Dispose when you want to stop receiving events
disposable.dispose();

val disposable: Disposable = channelController
    .subscribeFor<NewMessageEvent> { newMessageEvent ->
        // use newMessageEvent.message
    }
    
// Dispose when you want to stop receiving events
disposable.dispose()

All events at once

Disposable disposable = channelController.subscribe((ChatEvent event) -> {
    if (event instanceof NewMessageEvent) {
        // use ((NewMessageEvent) event).getMessage()
    }
    return Unit.INSTANCE;
});

// Dispose when you want to stop receiving events
disposable.dispose();

val disposable: Disposable = channelController
    .subscribe { event: ChatEvent ->
        when (event) {
            is NewMessageEvent -> {
                // use event.message
            }
        }
    }

// Dispose when you want to stop receiving events
disposable.dispose()

Client events

// Subscribe for User presence events
client.subscribeFor(
        new Class[]{UserPresenceChangedEvent.class},
        (ChatEvent chatEvent) -> {
            // Handle change
            return Unit.INSTANCE;
        }
);

// Subscribe for just the first ConnectedEvent
client.subscribeForSingle(ConnectedEvent.class,
        (ConnectedEvent event) -> {
            // Use event data
            int unreadCount = event.getMe().getTotalUnreadCount();
            int unreadChannels = event.getMe().getUnreadChannels();
            return Unit.INSTANCE;
        });

// Subscribe for User presence events
client.subscribeFor<UserPresenceChangedEvent>() { event: UserPresenceChangedEvent ->
    // Handle change
}

// Subscribe for just the first ConnectedEvent
client.subscribeForSingle<ConnectedEvent> { event: ConnectedEvent ->
    // Use event data
    val unreadCount = event.me.totalUnreadCount
    val unreadChannels = event.me.unreadChannels
}

Connection changed

client.subscribeFor(
        new Class[]{
                ConnectedEvent.class,
                ConnectingEvent.class,
                DisconnectedEvent.class
        },
        (ChatEvent chatEvent) -> {
            if (chatEvent instanceof ConnectedEvent) {
                // Socket is connected
            } else if (chatEvent instanceof ConnectingEvent) {
                // Socket is connecting
            } else if (chatEvent instanceof DisconnectedEvent) {
                // Socket is disconnected
            }
            return Unit.INSTANCE;
        }
);

client.subscribeFor(
    ConnectedEvent::class,
    ConnectingEvent::class,
    DisconnectedEvent::class
) { event ->
    when (event) {
        is ConnectedEvent -> {
            // Socket is connected
        }
        is ConnectingEvent -> {
            // Socket is connecting
        }
        is DisconnectedEvent -> {
            // Socket is disconnected
        }
    }
}

Stop listening

final Disposable disposable = client.subscribe(chatEvent -> {
    /* ... */
    return null;
});
disposable.dispose();

val disposable: Disposable = client.subscribe { /* ... */ }
disposable.dispose()

migration_docs.md

The contents of this document will be published on a wiki page, and linked to from the CHANGELOG and from the documentation page, so that existing users can easily migrate to the new APIs.

---

Changes to event subscriptions

The API for handling events from Chat has been updated, to make it simpler to use - and harder to misuse. We strongly suggest migrating to the new APIs.

The main change is that the intermediate ChatObservable class is being removed, and instead of chaining operators onto that and then subscribing to it, you can call subscribe-like methods on the ChatClient or ChannelController objects directly.

Here's how calls to the old API are replaced with the new API.

Please note that while the examples here are for the ChatClient, the API changes and migration steps are exactly the same for ChannelController.

Subscribing to all events

Old API

client.events().subscribe { event: ChatEvent ->
    if (event is NewMessageEvent) {
        val message = event.message
    }
}

New API

client.subscribe { event: ChatEvent ->
    if (event is NewMessageEvent) {
        val message = event.message
    }
}

Disposing a subscription (unsubscribing from events)

Old API

val subscription: Subscription = client.events().subscribe { /* ... */ }
subscription.unsubscribe()

New API

val disposable: Disposable = client.subscribe { /* ... */ }
disposable.dispose()

Filtering for event types

Filtering by the type field, by Strings

Old API

client.events()
    .filter("message.new")
    .filter("message.updated")
    .filter("message.deleted")
    .subscribe { event: ChatEvent ->
        /* ... */
    }

client.events()
    .filter("message.new")
    .filter("message.updated")
    .filter("message.deleted")
    .subscribe((ChatEvent event) -> {
        /* ... */
        return Unit.INSTANCE;
    });

New API

client.subscribeFor(
    "message.new",
    "message.updated",
    "message.deleted"
) { event: ChatEvent ->
    /* ... */
}

client.subscribeFor(
    new String[]{"message.new", "message.updated", "message.deleted"},
    (ChatEvent event) -> {
        /* ... */
        return Unit.INSTANCE;
    });

Filtering for built-in types

Old API

client.events()
    .filter(EventType.MESSAGE_NEW)
    .subscribe { event: ChatEvent ->
        /* ... */
    }

New API

client.subscribeFor(EventType.MESSAGE_NEW) { event: ChatEvent ->
    /* ... */
}

Filtering by event class

Old API

client.events()
    .filter(NewMessageEvent::class.java)
    .subscribe { event: ChatEvent ->
        /* ... */
    }

client.events()
    .filter(NewMessageEvent.class)
    .subscribe((ChatEvent event) -> {
        /* ... */
        return Unit.INSTANCE;
    });

New API

client.subscribeFor(NewMessageEvent::class) { event: ChatEvent ->
    /* ... */
}

client.subscribeFor<NewMessageEvent> { newMessageEvent: NewMessageEvent ->
    /* ... */
}

client.subscribeFor(
    new Class[]{NewMessageEvent.class},
    (ChatEvent event) -> {
        /* ... */
        return Unit.INSTANCE;
    });

Custom filtering

Old API

client.events()
    .filter { it.type == "my.custom.event" && it.createdAt < someDate }
    .subscribe { event: ChatEvent ->
        /* ... */
    }

New API

client.subscribe { event: ChatEvent ->
    if (event.type == "my.custom.event" && event.createdAt < someDate) {
        /* ... */
    }
}

Listening for a single event

Old API

client.events()
    .filter(ConnectedEvent::class.java)
    .first()
    .subscribe { event: ChatEvent
        Toast.makeText(this, "First connection", Toast.LENGTH_SHORT).show()
    }

client.events()
        .filter(ConnectedEvent.class)
        .first()
        .subscribe((ChatEvent event) -> {
            /* ... */
            return Unit.INSTANCE;
        })

New API

client.subscribeForSingle(ConnectedEvent::class.java) { event: ConnectedEvent ->
    Toast.makeText(this, "First connection", Toast.LENGTH_SHORT).show()
}

client.subscribeForSingle<ConnectedEvent> { event: ConnectedEvent
    Toast.makeText(this, "First connection", Toast.LENGTH_SHORT).show()
}

client.subscribeForSingle(ConnectedEvent.class,
    (ConnectedEvent event) -> {
        /* ... */
        return Unit.INSTANCE;
    });