Getting started with Java
Learn how to build serverside realtime provider with deepstream and Java
This page needs to be improved/might be out of date! Raise a PR if you feel like adding a few details or totally revamping it.
This guide will show you how to build backend processes in Java using deepstream’s three core concepts: Records, Events and RPCs.
Start your deepstream server
Connect to deepstream and log in
The first thing you’ll need to do is set up a Java project with gradle and add the following line to your build.gradle file.
compile 'io.deepstream:deepstream.io-client-java:2.0.4'From here we can instantiate a client as follows:
DeepstreamClient client = new DeepstreamClient("<Your app url here>");and log in (we didn’t configure any authentication, so there are no credentials required)
client.login();Records (realtime datastore)
[[glossary]] | Records are the documents in deepstream’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers. | Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures. | You can learn more about records in the records tutorial.
Creating a new record or retrieving an existent one is done using getRecord()
Record record = client.record.getRecord("test-record");Values can be stored using the .set() method
// you can set the whole record
JsonObject data = new JsonObject();
data.addProperty("name", "Alex");
data.addProperty("favouriteDrink", "coffee");
record.set(data);
// or just a path
record.set( "hobbies", new String[]{ "sailing", "reading" });and be retrieved using .get()
record.get(); // returns all record data as a JsonElement
record.get( "hobbies[1]" ); // returns the JsonElement 'reading'subscribe to changes by you or other clients using .subscribe()
//subscribe to changes made by you or other clients using .subscribe()
record.subscribe(new RecordChangedCallback() {
public void onRecordChanged(String recordName, JsonElement data) {
// some value in the record has changed
}
});
record.subscribe( "firstname", new RecordPathChangedCallback() {
public void onRecordPathChanged(String recordName, String path, JsonElement data) {
// the field "firstname" changed
}
});you can remove subscriptions with unsubscribe(), tell the server you’re no longer interested in the record using .discard() or delete it using .delete().
Events (publish-subscribe)
[[glossary]]
| Events are deepstream's publish-subscribe mechanism. Clients and backend processes can subscribe to event-names (sometimes also called “topics” or “channels”) and receive messages published by other endpoints.
| Events are non-persistent, one-off messages. For persistent data, please use records.
| Events, aka Pub/Sub, allows communication using a Publish-Subscribe pattern. A client/server emits an event, which is known as publishing and all connected (subscribed) clients/servers are triggered with the event's payload if any. This is a common pattern, not just in realtime systems, but software engineering generally.
Clients and backend processes can receive events using .subscribe()
client.event.subscribe("test-event", new EventListener() {
public void onEvent(String eventName, Object data) {
// do something with data
}
});… and publish events using .emit()
client.event.emit( "test-event", "some data");RPCs (request-response)
[[glossary]] | Remote Procedure Calls are deepstream's request-response mechanism. Clients and backend processes can register as “providers” for a given RPC, identified by a unique name. Other endpoints can request said RPC. | deepstream will route requests to the right provider, load-balance between multiple providers for the same RPC, and handle data-serialisation and transport.
You can make a request using .make()
JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("a", 7);
jsonObject.addProperty("b", 8);
RpcResult rpcResult = client.rpc.make( "multiply-numbers", jsonObject);
int result = (Integer) rpcResult.getData(); // 56and answer it using .provide()
client.rpc.provide("multiply-numbers", new RpcRequestedListener() {
public void onRPCRequested(String name, Object data, RpcResponse response) {
Gson gson = new Gson();
JsonObject jsonData = (JsonObject) gson.toJsonTree(data);
int a = jsonData.get("a").getAsInt();
int b = jsonData.get("b").getAsInt();
response.send(a * b);
}
});