Background Image Background Image;

Diffusion Quick Start Guide

Choose product:
Choose client:

Contents

Introduction to the Diffusion Intelligent Data Platform

The Diffusion platform makes it simple, fast and efficient to move real-time data across the Internet. Diffusion provides multiple ways to send and receive data: publish and subscribe real-time broadcast, one-off data queries (“fetch”), and request/response services.

About this Guide

This Quick Start Guide gives you an introduction to Diffusion and how to use it. It covers setting up your first Diffusion instance, and using the core publish and subscribe broadcast mechanism to send and receive data.

For detailed documentation on the rich features of the Diffusion platform, please visit our documentation site for full user manuals and examples.

This Guide was last updated for Diffusion 6.2.

Choose your Product and Language

  1. You have a choice of using Diffusion (hosted on-premise or in your private cloud) or Diffusion Cloud (hosted on Push Technology servers).

    Use the selector on the left to switch this Guide to the product you want.

    Currently, Diffusion Cloud is selected.

  2. There are Diffusion client libraries for most major programming languages.

    Use the selector on the upper left to see examples in this Guide in your preferred language. (Examples for the C library are not yet available, but are coming soon).

Setting up Diffusion

To begin using Diffusion, we first need an instance of Diffusion to develop against. There are free trial options available for both Diffusion Cloud and Diffusion (on-premise) versions. Let’s get one running!

  1. To start using Diffusion Cloud, first sign up for a free account.

    Once you’ve verified your email, you will be presented with a form to set up a new Diffusion Cloud service.

    Under Service Region, select the region nearest to you.

    Under Service Version, select the newest version available.

  2. Once you’ve created the new service, you’ll be taken to the Diffusion Cloud Account Home. 

     

  3. To finish setting up your Diffusion Cloud instance, click the Manage button to the right of the service you just created.

    You’ll be prompted to specify authentication details for the “admin” user account. These are separate from the account details you use to log in to Diffusion Cloud. They can be used to access the Diffusion service from a remote client, so it’s important to choose a strong password.

  4. Once you’ve set up your admin details, you’ll see the Service Dashboard.

    Take note of the hostname that your Diffusion service has been assigned. You can find this in the Service Details table in the line beginning Host:

    Copy this hostname, as we will be using it in later sections to connect to Diffusion and start sending and receiving data.

Creating a Session

All interactions with Diffusion are done via our client libraries. When you use a client library to connect to Diffusion, this creates a session. A session is able to send and receive data and acts as the intermediary between Diffusion and your application code.

Let’s create a session, which we will then use to try out various features of Diffusion.

  1. To use Diffusion within the browser, simply include the Diffusion JavaScript client in the <head> of your HTML.

    <script src="http://download.pushtechnology.com/clients/latest/js/diffusion.js"></script>
    

    If you are using NPM, you can add our NPM module by running

    npm install --save diffusion

    Then import the library within your code with:

    const diffusion = require('diffusion')
  2. Now that we have the Diffusion client available, let’s connect to Diffusion. We’ll be using the Diffusion host/port details as well as the admin credentials found in the previous step of this guide, so make sure you have them to hand.

  3. Add the following lines to connect to Diffusion.

    diffusion.connect({
        host : "<HOST>",
        port : <PORT>,
        principal : "<USERNAME>",
        credentials : "<PASSWORD>"
    }).then(function(session) {
        // Use the new session here
    });

Publishing Data

Publish and subscribe real-time broadcast is one of the key ways of using Diffusion to move data in real time.

Neither publishers nor subscribers need to know about the existence of each other, which lets you simplify your code to care solely about the data, not who is using it.

To publish data, your client must specify a topic.

A topic:

  • contains a specified type of data, for example, JSON
  • has a unique path

Topic paths are structured into hierarchies using the / character, much like URLs. For example, a set of topics used for streaming telemetry data from ships might have paths like:

/telemetry/gps/ss-victoria
/telemetry/gps/ss-narwhal
/telemetry/gps/ss-leo

This makes it easy to organize related topics, and for subscribers to select data at different levels of granularity. For example, a subscriber that needs the GPS data for all the ships can subscribe to all topics matching the path:

/telemetry/gps/

Unlike other messaging products, Diffusion allows you to have millions of unique topics. You can use as many or as few as needed to represent your desired data structure.

To begin, we first need to create a topic. Then we’ll start publishing data to it.

  1. Let’s start by creating a JSON topic.

    session.topics.add('my-topic',diffusion.topics.TopicType.JSON);
  2. Now that the topic exists, we can publish data to it.

    var value = { foo : "bar" }
    var result = session.topicUpdate.set("my-topic", diffusion.datatypes.json(), value);

    It’s as easy as that!

Subscribing to Data

A session can subscribe to data published to topics. Subscription is a way for a session to tell Diffusion which topics it’s interested in. Diffusion will cache your subscriptions, so you can subscribe to topics which don’t yet exist, and retain full subscription state should your session disconnect and reconnect.

You can use security policies to determine which topics a session can subscribe to.

When a session subscribes to an existing topic, Diffusion will send that topic’s current value to the session immediately, and then send any subsequent updates as they arrive. This allows Diffusion to act as a cache, where subscribers are always guaranteed to get the latest value.

Now that we’ve created a topic and published some data to it, let’s add a subscription to pull out the value.

  1. Before we subscribe, we need to first attach a stream to listen for updates.

    session.stream('my-topic').asType(diffusion.datatypes.json()).on('value', (path, topicSpec, value) => {
     console.log(`New value for ${path}: ${value.get()`);
    });

    Now we can tell Diffusion that we want to receive updates from the topic we created.

    session.subscribe('my-topic');
  2. Note that you can create multiple streams to dispatch updates to different parts of your application.

Next Steps

That’s it – we’ve successfully created a Diffusion client that creates a topic, publishes updates, and receives values!

If you run the example, you will see a console log containing the values that we updated the topic with. Try modifying the example code to publish different values – or publish multiple values using a timer to see how Diffusion provides real-time data delivery.

Why not try implementing a publishing client and a subscribing client in different languages to get a feel for how Diffusion can simplify communications between back-end and front-end platforms?

  1. To learn more about the Diffusion JavaScript SDK, please browse the API Documentation.

  2. To learn more about how to use Diffusion Cloud, please refer to our Diffusion Cloud Manual for in-depth documentation on every aspect of the service.

  3. More advanced code examples are available on our GitHub page.