mitter.io
Search…
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:
1
repositories {
2
jcenter()
3
}
4
5
dependencies {
6
compile group: 'io.mitter', name: 'java-sdk', version: '0.5.5'
7
}
Copied!

Configuring the Client

The main point of access is the MitterCentralClientFactory. Create the factory like so:
1
import io.mitter.sdk.java.MitterCentralClientFactory;
2
3
MitterCentralClientFactory factory = new MitterCentralClientFactory(
4
new MitterApplicationAccessKeyCredentials(
5
"my-application-access-key",
6
"my-application-access-secret"
7
)
8
);
Copied!
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:
1
mitterCentralClientFactory.usersClient()
2
.newUser(
3
new User(
4
"princess-carolyn", //the userId
5
new ScreenName()
6
.setScreenName("Princess Carolyn")
7
)
8
);
Copied!
Channel Operations
Channel operations are performed using the MitterChannelsClient, which can be acquired and used as follows:
1
mitterCentralClientFactory.channelsClient()
2
.newChannel(
3
new Channel(
4
"bojack-intervention", //the channelId
5
"io.mitter.ruleset.chats.GroupChat", //the group chat ruleset
6
Lists.newArrayList(
7
new ChannelParticipation(IdUtils.of("princess-carolyn", User.class)), //Converting a string to mitter Identifiable
8
new ChannelParticipation(IdUtils.of("mister-peanutbutter", User.class))
9
)
10
false // whether systemChannel or not
11
)
12
);
Copied!
Message Operations
Send Messages using the MitterMessagesClient:
1
mitterCentralClientFactory.messagesClient()
2
.sendMessageToChannel(
3
//Channel id
4
IdUtils.of("bojack-intervention", Channel.class),
5
6
new Message(
7
//message id
8
"message-1",
9
10
//Sender id
11
IdUtils.of("intervention-coordinator", User.class),
12
13
//Text of the message
14
"Welcome to BoJack's Intervention. Grab some popcorn",
15
16
//A list of TimelineEvents. You can send as many as you want
17
List.newArrayList(
18
19
//mitter mandates that the SentTime MUST be sent
20
new TimelineEvent(
21
"event-id-1",
22
StandardTimelineEventTypeNames.Messages.SentTime,
23
new Date().getTime(),
24
IdUtils.of("intervention-coordinator", User.class)
25
)
26
)
27
)
28
)
Copied!
Send custom payloads:
1
mitterCentralClientFactory.messagesClient()
2
.sendMessageToChannel(
3
4
//Channel id
5
IdUtils.of("bojack-intervention", Channel.class),
6
7
new Message(
8
//message id
9
"message-2",
10
11
IdUtils.of("intervention-coordinator", User.class),
12
13
14
//A text representation is mandatory, even for custom payload messages
15
"Here's some entertainment meanwhile",
16
17
//Send custom payloads
18
Lists.newArrayList(
19
new MessageDatum(
20
// Custom data type
21
"embarassing-bojack-story",
22
23
// Send any JSON
24
new JsonNode()
25
),
26
new MessageDatum(
27
"baby-bojack-pics",
28
new JsonNode()
29
)
30
),
31
32
List.newArrayList(
33
new TimelineEvent(
34
"event-id-1",
35
StandardTimelineEventTypeNames.Messages.SentTime,
36
new Date().getTime(),
37
IdUtils.of("intervention-coordinator", User.class)
38
)
39
)
40
)
41
)
Copied!
Get very specific messages with a query:
1
mitterCentralClientFactory.getMessagesClient()
2
.getMessagesFromChannel(channelId,
3
4
// Fetch query for messages
5
MitterMessagesHelper.messageQuery(
6
// No. of messages to fetch
7
50,
8
9
// 'beforeId': Fetch only before this message
10
IdUtils.of("message-id-100", Message.class),
11
12
// 'afterId': Fetch only after this message
13
IdUtils.of("message-id-50", Message.class),
14
15
16
// fetch messages with any of these payloadTypes only
17
Lists.newArrayList(
18
"intervention-time-update"
19
)
20
)
21
)
Copied!
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
Last modified 3yr ago