The Magistral Data Stream Network

The elastic infrastructure to build and connect your realtime IoT apps

Get one of available Magistral SDKs

Java Android
(coming soon)
JS (coming soon) Go (coming soon) Ruby (coming soon) Python Swift
C++ (coming soon) .NET (coming soon) PHP (coming soon) Scala (coming soon) Clojure (coming soon) Perl (coming soon) Erlang (coming soon)

Magistral Java SDK

To Use Magistral messaging API in Java environment you need simply to get a copy of Java SDK — magistral-1.0.jar [download] file into your project working directory. There are several dependencies you need to provide in classpath in addition to SDK itself:

Maven dependencies [expand]

<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-clients</artifactId>
<version>0.10.0.0</version>
</dependency>
<dependency>
<groupId>com.googlecode.json-simple</groupId>
<artifactId>json-simple</artifactId>
<version>1.1.1</version>
</dependency>
<dependency>
<groupId>org.eclipse.paho</groupId>
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
<version>1.1.0</version>
</dependency>

Magistral Java SDK supports Java not earlier than version 8.

To connect Magistral SDK to your java project you can use maven dependency. Firstly, add Magistral maven repository into the pom.xml file:

<repositories>
...
<repository>
<id>Magistral SDK Repository</id>
<url>https://repo.magistral.io/archiva/repository/releases</url>
</repository>
...
</repositories>

Then include available SDK version into pom dependencies section:

<dependencies>
...
<dependency>
<groupId>io.magistral.sdk</groupId>
<artifactId>magistral</artifactId>
<version>1.0</version>
</dependency>
...
</dependencies>

all other dependencies used by Magistral Java SDK will be downloaded automatically. Your development environment is ready now to get started with real-time messaging.

Examples to ease setup and configuration

Here we give a couple of examples to ease setup and configuration of your apps to work with Magistral.

1. Create an Application.

If you still have not created any applications yet, there is a good time to do that. You can do it through the service page. Please signin and go to applications page (select “Application” item in left menu). Click “New” and input a name for your new brand app. Let’s call it “Greeting Service”. After confirmation application will be available in the application list.

Clicking on newly created app in the table you will be forwarded to special page, where you can find publish and subscribe keys needed later on to set up Magistral application instance, connect to the network and send messages. Use clipboard buttons in the end of each key to use these copies when creating Magistral app instance.

2. Creation of topic

The next step will be creation of topic. In topic page click “New” and select application in opened dialog, where it should be created. Then specify name of the topic and number of channels needed . (More about topics and channels you can find here).

Let’s create Topic “greetings” with 2 channels.

3. Ready to connect and transmit

Now you have everything ready to connect and transmit data through the Magistral. Remaining third key (secret key) needed to connect to the Magistral Network you can find in User Management panel. Just click on the key icon in last table column to put it into the clipboard.

We will use existing permissions (which were created automatically for super-user) to publish messages.

4. Create additional users

Doing nothing with super-user permissions, we create 2 additional users Joe and Moe, who will have a read permissions only for one of previously created channels of “greetings” topic. In this way we isolate users from data feeds, that are not intended (in our demo case) to be shared among them.

Further, we click on link of newly created user in the table and press then “Grant” button. In opened dialog we select right Application and Topic in top comboboxes and leave only Read checkbox selected. In the table with channels we select channel ‘0’ for Joe and repeat the same procedure for Moe, granting read permission from channel ‘1’.

5. Create instances

Next, we create Magistral instances for Moe and Joe and connect to the Network using publish and subscribe keys (from step 1) and secret key obtained on previous step.

Magistral m = new Magistral(‘pubKey’, ‘subKey’, ‘secretKey’);

Subscribing to “greetings” topic and listen to messages sent over it.

magistral.subscribe(“greetings”, 0, new NetworkListener() {
public void messageReceived(MessageEvent e) {
String msg = new String(e.msgBody(), StandardCharsets.UTF_8);
System.out.println(“Great! I’ve got a message : ” + msg);
}
public void disconnected(String topic) {
System.out.println("Disconnected from '" + topic + "'");
}
public void reconnect(String topic) {
System.out.println("Reconnect on '" + topic + "'");
}
public void connected(String topic) {
System.out.println("Connected to '" + topic + "'");
}
public void error(MagistralException ex) {
System.out.println(ex.getMessage());
}
});

Then, from the other Magistral instance created with super-user credentials and launched on this or any other machine, we sent a message to channel ‘0’, listened by Joe.

byte[] msg = "Hi Joe!".getBytes(StandardCharsets.UTF_8);
m.publish("greetings", 0, msg, new Callback() {
public void success(PubMeta meta) {
System.out.println("Message has been successfully sent");
}
public void error(MagistralException ex) {
System.out.println(ex.getMessage());
}
});

The message will be immediately delivered to Joe’s end point and will be printed out as described in example. In the same way procedure it will work and for Moe via channel ‘1’.

Caveat! There are two publish methods presented in Magistral API. If channel parameter is not explicitly specified, then message will be sent to all available channels current user has permission to write to. Each data packet transmission will be processed and counted separately.

5. Congratulations, we finished setup and started to use Magistral Cloud messaging service just in minutes.

Following described procedure steps you can quickly configure Magistral to fit the logic of your real-time applications. Try features of Magistral API, which allow you to read historical data, automate management of available messaging resources, granting and revoking permissions, and etc. to seamlessly integrate Magistral into your processes.