Java (Backend)

The Java SDK for backends

Introduction

The Java SDK is a backend SDK that can be used to communicate with Mitter.io. It provides the following high level functionalities:

1. Create and delete Users

2. Create and delete Channels

3. Get and send Messages

4. Get and send Timeline Events

Being a backend SDK, the Java SDK connects with Mitter.io via HTTP only.

Getting the SDK

The Java SDK is available on jcenter. Add this to you build.gradle:

repositories {
    jcenter()
}

dependencies {
    compile group: 'io.mitter', name: 'java-sdk', version: '0.5.5'
}

Configuring the Client

The main point of access is the MitterCentralClientFactory. Create the factory like so:

import io.mitter.sdk.java.MitterCentralClientFactory;

MitterCentralClientFactory factory = new MitterCentralClientFactory(
        new MitterApplicationAccessKeyCredentials(
                "my-application-access-key", 
                "my-application-access-secret"
        )
);

This will authenticate you with an Application Principal. This is the most common type of credential you will need when you make calls from your backend.

You can also authenticate as:

1. The Subscriber (the entity you created you Mitter.io account with) using MitterSubscriberApiAccessCredentials

2. A User, using MittterUserTokenCredentials

3. Anonymously, using MitterAnonymousCredentials

Do note that each principal has restricted access to APIs. A Subscriber, for instance, cannot send Messages to a Channel, and an Application cannot create other Applications.

Refer to the Platform Reference docs for the full list of operations each Principal can perform.

Access Mitter.io

You can access the different clients using MitterCentralClientFactory

User Operations

Users operations are done through the MitterUsersClient, as follows:

mitterCentralClientFactory.usersClient()
        .newUser(
                new User(
                    "princess-carolyn", //the userId
                    new ScreenName()
                        .setScreenName("Princess Carolyn")
                )
        );

Channel Operations

Channel operations are performed using the MitterChannelsClient, which can be acquired and used as follows:

mitterCentralClientFactory.channelsClient()
        .newChannel(
                new Channel(
                    "bojack-intervention", //the channelId
                    "io.mitter.ruleset.chats.GroupChat", //the group chat ruleset
                    Lists.newArrayList(
                        new ChannelParticipation(IdUtils.of("princess-carolyn", User.class)), //Converting a string to mitter Identifiable
                        new ChannelParticipation(IdUtils.of("mister-peanutbutter", User.class))        
                    )
                    false // whether systemChannel or not
                )
        );

Message Operations

Send Messages using the MitterMessagesClient:

mitterCentralClientFactory.messagesClient()
        .sendMessageToChannel(
                //Channel id
                IdUtils.of("bojack-intervention", Channel.class),

                new Message(
                        //message id
                        "message-1",

                        //Sender id
                        IdUtils.of("intervention-coordinator", User.class),

                        //Text of the message
                        "Welcome to BoJack's Intervention. Grab some popcorn",

                        //A list of TimelineEvents. You can send as many as you want
                        List.newArrayList(

                                //mitter mandates that the SentTime MUST be sent
                                new TimelineEvent(
                                        "event-id-1",
                                        StandardTimelineEventTypeNames.Messages.SentTime,
                                        new Date().getTime(),
                                        IdUtils.of("intervention-coordinator", User.class)
                                )
                        )
                )
        )

Send custom payloads:

mitterCentralClientFactory.messagesClient()
        .sendMessageToChannel(

                //Channel id
                IdUtils.of("bojack-intervention", Channel.class),

                new Message(
                        //message id
                        "message-2",

                        IdUtils.of("intervention-coordinator", User.class),


                        //A text representation is mandatory, even for custom payload messages
                        "Here's some entertainment meanwhile",

                        //Send custom payloads
                        Lists.newArrayList(
                                new MessageDatum(
                                        // Custom data type
                                        "embarassing-bojack-story",

                                        // Send any JSON
                                        new JsonNode()
                                ),
                                new MessageDatum(
                                        "baby-bojack-pics",
                                        new JsonNode()
                                )
                        ),

                        List.newArrayList(
                                new TimelineEvent(
                                        "event-id-1",
                                        StandardTimelineEventTypeNames.Messages.SentTime,
                                        new Date().getTime(),
                                        IdUtils.of("intervention-coordinator", User.class)
                                )
                        )
                )
        )

Get very specific messages with a query:

mitterCentralClientFactory.getMessagesClient()
        .getMessagesFromChannel(channelId,

                // Fetch query for messages
                MitterMessagesHelper.messageQuery(
                    // No. of messages to fetch    
                    50,

                    // 'beforeId': Fetch only before this message
                    IdUtils.of("message-id-100", Message.class),

                    // 'afterId': Fetch only after this message 
                    IdUtils.of("message-id-50", Message.class),


                    // fetch messages with any of these payloadTypes only
                    Lists.newArrayList(
                            "intervention-time-update"
                    )
                )
        )

Other Operations

The SDK has a few other clients for operations on Timeline Events, User Presence, Channel Streams, etc.

The APIs are very similar to the ones shown above, and you should have no problem navigating through them.

High Level Clients

Certain APIs on Mitter.io are paginated, like Channels and Messages. So when you do something like messagesClient.getMessagesFromChannel(channelId) you will only get the default 50 messages, and to get more messages, you will have to build a query and call getMessagesFromChannel.

The SDK makes it easy to use these paginated APIs without worrying about the pagination scheme or maintaining the pagination tokens, by providing high level clients.

The MitterMessagesHlcClient provides the following convenience functions:

• getAllExistingMessages(channelId)

• getAllMessagesAfter(channelId, messageId)

• getAllMessagesBefore(channelId, messageId)

You don't need to worry about these functions being intensive operations, because they provide lazy lists.

High Level Clients return Iterators, so more pages will not be fetched unless you iterate and reach the end.

Notes

• The SDK is itself written in Kotlin, and fully supports most JVM languages

• To be able to send JSON in custom payloads, the SDK uses JsonNode from Jackson