The Magistral Data Stream Network

The elastic infrastructure to build and connect your realtime IoT apps
Java SE API Reference

Native Magistral API

  • Connecting

    Description

    Initializes Magistral application instance.
    With initialized instance user can publish and consume messages and perform all other operations provided by API.
    Magistral magistral = new Magistral(String pubKey, String subKey, String secretKey);
    Parameter Description Required Type
    pubKey Application key needed to publish messages Yes String
    subKey Application key needed to consume messages Yes String
    secretKey Application key needed to authorize user Yes String
    Magistral magistral = new Magistral(String pubKey, String subKey, String secretKey, String cipher);
    Parameter Description Required Type
    pubKey Application key needed to publish messages Yes String
    subKey Application key needed to consume messages Yes String
    secretKey Application key needed to authorize user Yes String
    cipher AES encryption key Yes String
  • Subscribe

    Description

    This function causes the client to initiate subscription to the Magistral DSN and to begin listening of messages on the topic level (all channels) or on specific channel. Subscriptions made from one group (default group name - “default”) are delivered only to one user from this group.
    Future<SubMeta> res = magistral.subscribe(String topic, NetworkListener listener, Callback callback);
    Parameter Description Required Type
    topic Topic to subscribe to Yes String
    listener Triggered when new message is received Yes Network Listener
    callback Ack object, containing success or error callback No Callback
    Future<SubMeta> res = magistral.subscribe(String topic, int channel, NetworkListener listener, Callback callback);
    Parameter Description Required Type
    topic Topic to subscribe to Yes String
    channel Number of channel to listen to Yes int
    listener Triggered when new message is received Yes Network Listener
    callback Ack object, containing success or error callback No Callback
    Future<SubMeta> res = magistral.subscribe(String topic, String group, NetworkListener listener, Callback callback);
    Parameter Description Required Type
    topic Topic to subscribe to Yes String
    group Name of the user group Yes String
    listener Triggered when new message is received Yes Network Listener
    callback Ack object, containing success or error callback No Callback
    Future<SubMeta> res = magistral.subscribe(String topic, String group, int channel, NetworkListener listener, Callback callback);
    Parameter Description Required Type
    topic Topic to subscribe to Yes String
    group Name of the user group Yes String
    channel Number of channel to listen to Yes int
    listener Triggered when new message is received Yes Network Listener
    callback Ack object, containing success or error callback No Callback

    Usage example

    magistral.subscribe(“bus”, “operator”, 52, new NetworkListener() {
         public void messageReceived(MessageEvent e) {
              String topic = e.topic();
              int channel = e.channel();
              String msg = new String(e.msgBody(), StandardCharsets.UTF_8);
              System.out.println(“Location of ” + topic + “ No ” + channel + “ is ” + 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());
         }
    });
  • Unsubscribe

    Description

    This function causes the client to close connection and stop listening of messages sent via single channel or group of channels combined within their topic.
    Future<SubMeta> res = magistral.unsubscribe(String topic);
    Parameter Description Required Type
    topic Topic name Yes String
    Future<SubMeta> res = magistral.unsubscribe(String topic, int channel);
    Parameter Description Required Type
    topic Topic name Yes String
    channel Channel number Yes int
  • Publish

    Description

    Publishes messages to Magistral network.
    If channel was not explicitly specified, then message will be sent to a random channel.
    Future<PubMeta> res = magistral.publish(String topic, byte[] msg, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    msg Message to be sent in binary form Yes byte[]
    callback Ack object, containing success or error callback No Callback
    Future<PubMeta> res = magistral.publish(String topic, int channel, byte[] msg, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    channel Channel number Yes int
    msg Message to be sent in binary form Yes byte[]
    callback Ack object, containing success or error callback No Callback

    Usage example

    magistral.publish(“bus”, 52, “55.598707, 37.035291”.getBytes(StandardCharsets.UTF_8), new Callback() {
         public void success(PubMeta meta) {
              String topic = meta.getTopic();
              int channel = meta.getChannel();
              System.out.println("Send updated coordinates for " + topic + " No " + channel);
         }
         public void error(MagistralException ex) {
              System.out.println(ex.getMessage());
         }
    });

Network resources

  • Topic and channels

    Description

    Method returns information about available topics and channels for current user.
    Future<List<TopicMeta>> res = magistral.topics(Callback callback);
    Parameter Description Required Type
    callback Ack object, containing success or error callback No Callback

    Description

    Method returns detailed information about topic and its channels.
    Future<TopicMeta> res = magistral.topic(String topic, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    callback Ack object, containing success or error callback No Callback

    Usage example

    magistral.topic(“bus”, new Callback() {
         public void success(List<TopicMeta> meta) {
              TopicMeta topicInfo = meta.get(0);
              System.out.println("For topic '" + topicInfo.getName() + "' following channels are available [" + topicInfo.getСhannels() + "]");
         }
         public void error(MagistralException ex) {
              System.out.println(ex.getMessage());
         }
    });

Access Control

  • Get permissions

    Description

    Returns all permissions for topics and channels granted for requesting user. By default, super user can see all topics and channels.
    Future<List<PermMeta>> res = magistral.permissions(Callback callback);
    Parameter Description Required Type
    callback Ack object, containing success or error callback No Callback

    Description

    Permissions granted for specific topic.
    Future<List<PermMeta>> res = magistral.permissions(String topic, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    callback Ack object, containing success or error callback No Callback

    Usage example

    magistral.permissions("bus", new Callback() {
         public void success(List<PermMeta> meta) {
              for (PermMeta pm : meta) {
                   for (int ch : pm.channels()) {
                        System.out.println("Permissions for [" + pm.topic() + ":" + ch + "] are "
                        + "[read : " + pm.readable(ch) + ", write : " + pm.writable(ch) + "]");
                   }
              }
         }
         public void error(MagistralException ex) {
              System.out.println(ex.getMessage());
         }
    });
  • Grant permissions

    Description

    Method allows to grant permanent or temporary permissions to publish and consume messages from topics and channels.
    If channel is not explicitly defined - permissions will be granted for all channels in topic.

    Permissions can be granted only by super user.

    Future<List<PermMeta>> res = magistral.grant(String user, String topic, boolean read, boolean write, Callback callback);
    Parameter Description Required Type
    user User name given in User Management module Yes String
    topic Topic name Yes String
    read Whether user can publish messages to the topic Yes boolean
    write Whether user can read messages from the topic Yes boolean
    callback Ack object, containing success or error callback No Callback
    Future<List<PermMeta>> res = magistral.grant(String user, String topic, boolean read, boolean write, int ttl, Callback callback);
    Parameter Description Required Type
    user User name (given in User Management module) Yes String
    topic Topic name Yes String
    read Read permission Yes boolean
    write Write permission Yes boolean
    ttl Time to live for permission Yes int
    callback Ack object, containing success or error callback No Callback
    Future<PermCallback> res = magistral.grant(String user, String topic, int channel, boolean read, boolean write, Callback callback);
    Parameter Description Required Type
    user User name given in User Management module Yes String
    topic Topic name Yes String
    channel Channel index Yes int
    read Read permission Yes boolean
    write Write permission Yes boolean
    callback Ack object, containing success or error callback No Callback
    Future<List<PermMeta>> res = magistral.grant(String user, String topic, int channel, boolean read, boolean write, int ttl, Callback callback);
    Parameter Description Required Type
    user User name given in User Management module Yes String
    topic Topic name Yes String
    channel Channel index Yes int
    read Read permission Yes boolean
    write Write permission Yes boolean
    ttl Time to live for permission Yes int
    callback Ack object, containing success or error callback No Callback

    Usage example

    magistral.grant("user@magistral.io", "bus", 52, true, true, new io.magistral.client.perm.Callback() {
         public void success(List<PermMeta> meta) {
              System.out.println("Permissions were successfully granted.");
              System.out.println("Current permissions list:");
              for (PermMeta pm : meta) {
                   for (int ch : pm.channels()) {
                        System.out.println("[" + pm.topic() + ":" + ch + "] : [readable : " + pm.readable(ch) + ", writable : " + pm.writable(ch) + "]");
                   }
              }
         }
         public void error(MagistralException ex) {
              System.out.println(ex.getMessage());
         }
    });
  • Revoke permissions

    Description

    Method allows to revoke already granted permissions. If channel parameter is not specified - permissions will be revoked for all topic channels
    Future<List<PermMeta>> res = magistral.revoke(String user, String topic, Callback callback);
    Parameter Description Required Type
    user User name given in User Management module Yes String
    topic Topic name Yes String
    callback Ack object, containing success or error callback No Callback
    Future<List<PermMeta>> res = magistral.revoke(String user, String topic, int channel, Callback callback);
    Parameter Description Required Type
    user User name given in User Management module Yes String
    topic Topic name Yes String
    channel Channel index Yes int
    callback Ack object, containing success or error callback No Callback

History

  • Data import

    Description

    Magistral data import feature provides real-time access to history for all messages sent via Magistral. Messages can be encrypted with AES encryption to ensure that they are not readable to anybody else except owner of cipher.
    Future<History> res = magistral.history(String topic, int channel, int count, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    channel Channel number Yes int
    count Number of messages to be fetched (Limited by 100K) Yes int
    callback Ack object, containing success or error callback No Callback
    Future<History> res = magistral.history(String topic, int channel, long start, int count, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    channel Channel number Yes int
    start Timestamp (in milliseconds) to pull messages from Yes long
    count Number of messages to be fetched (Limited by 100K) Yes int
    callback Ack object, containing success or error callback No Callback
    Future<History> res = magistral.history(String topic, int channel, long start, long end, Callback callback);
    Parameter Description Required Type
    topic Topic name Yes String
    channel Channel number Yes int
    start Timestamp (in milliseconds) to pull messages from Yes long
    end Timestamp delimiting end of epoch
    ! Should not exceed start point more than 86400000 ms (24h)
    Yes long
    callback Ack object, containing success or error callback No Callback

    Usage example

    final int msgCount = 100;
    magistral.history("bus", 52, msgCount, new io.magistral.client.data.Callback() {
         public void success(History history) {
              System.out.println("Last " + msgCount + " messages are: ");
              for (Message msg : history.getMessages()) {
                   System.out.println(new String(msg.getBody(), StandardCharsets.UTF_8) + " at " + msg.getTime());
              }
         }
         public void error(MagistralException ex) {
              System.out.println(ex.getMessage());
         }
    });