Conditional Pub/Sub

The example demonstrates publishing a weather forecast message with headers which can be used to create a conditional subscriber. The subscriber uses a selector to get weather forecast messages for the Dallas area when the expected temperature is higher than 60F degrees. The message is published into the demo channel.

Subscriber

Important

Make sure to replace xxxx in the domain name in the sample requests below to the one assigned to your application.

Establishing a subscription

Request:

curl -H Content-Type:application/json -X POST -d '{ "selector":"city = '\''Dallas'\'' and temperature > 60"}' \
-v https://xxxx.backendless.app/messaging/demo/subscribe

Response:

{
  "subscriptionId" : "1111-1111-1111-11111"
}

Retrieving messages

Request:

curl -X GET 
-v https://xxxx.backendless.app/messaging/demo/1111-1111-1111-11111

Response:

{
  "messages": [
    {
      "headers": {
        "temperature": "62",
        "DSId": "FEA0EAD5-51FE-5A8D-FF09-647CD75FCC00",
        "state": "Texas",
        "DSDstClientId": "63148CEC-9BB2-9B8F-FF4C-FCE56A829A00",
        "BL_APPLICATION_ID": "APP-ID",
        "city": "Dallas"
      },
      "publisherId": null,
      "data": "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.",
      "publishedAt": 1524907478264,
      "messageId": "message:2448AE97-8707-CF49-FFE9-9DBCF4B3DC00"
    }
  ]
}

Codeless Reference

where:

Argument	Description
id	The unique identifier of the event listener.
channel	Name of the channel to subscribe to.
selector	A selector is a query expressed in the SQL-92 syntax and formatted as the condition part of the SQL's WHERE clause. The condition references headers in the published messages.
message	When a listener gets triggered, it assigns data of the message matching the where clause condition to this variable(message).

This operation does not return a value.

The example below creates a message listener with id "1111-1111-1111-11111" for the "demo" channel. The selector property is set to listen to only those messages whose headers contain the "city" property with 'Dallas' value and "temperature" property whose value is higher than 60. By setting this condition, only specific(filtered) messages will trigger the listener.

When a message containing the aforementioned headers is published to the "demo" channel the listener gets triggered and saves the message content to the message variable. Then the data stored in the message variable gets printed.

Publisher

RESTJavaScriptAndroidSwiftObjective-CC#Flutter

curl -X POST \
  https://api.backendless.com/APP-ID/REST-API-KEY/messaging/demo \
  -H 'content-type: application/json' \
  -d '{  "message": "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.", 
         "headers" : { 
             "city" : "Dallas",
             "state" : "Texas", 
             "temperature":62    
         }                  
      }'

var message = "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.";
var publishOptions = new Backendless.PublishOptions({
       headers: {
          "city": "Dallas",
          "state": "Texas",
          "temperature": 62
       }
   });

Backendless.Messaging.publish( "demo", message, publishOptions )
 .then( function( result ) {
    console.log( "message has been published" );
  })
 .catch( function( error ) {
    console.log( "error publishing the message - " + error );
  })

String message = "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.";
PublishOptions publishOptions = new PublishOptions();
publishOptions.putHeader( "city", "Dallas" );
publishOptions.putHeader( "state", "Texas" );
publishOptions.putHeader( "temperature", 62);

Backendless.Messaging.publish( "demo", 
                               message,
                               publishOptions, 
                               new AsyncCallback<MessageStatus>()
{
  @Override
  public void handleResponse( MessageStatus response )
  {
    Log.i( "MYAPP", "Message has been published" );  
  }

  @Override
  public void handleFault( BackendlessFault fault )
  {
    Log.e( "MYAPP", "Error publishing the message" );
  }
} );

let message = "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%."

let publishOptions = PublishOptions()
publishOptions.addHeader(name: "city", value: "Dallas")
publishOptions.addHeader(name: "state", value: "Texas")
publishOptions.addHeader(name: "temperature", value: 62)

Backendless.shared.messaging.publish(channelName: "demo", message: message, publishOptions: publishOptions, responseHandler: { messageStatus in
    print("Message has been published")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

NSString *message = @"Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.";

PublishOptions *publishOptions = [PublishOptions new];
[publishOptions addHeaderWithName:@"city" value:@"Dallas"];
[publishOptions addHeaderWithName:@"state" value:@"Texas"];
[publishOptions addHeaderWithName:@"temperature" value:@62];

[Backendless.shared.messaging publishWithChannelName:@"demo" message:message publishOptions:publishOptions responseHandler:^(MessageStatus *messageStatus) {
    NSLog(@"Message has been published");
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

AsyncCallback<MessageStatus> callback = new AsyncCallback<MessageStatus>(
   messageStatus =>
   {
     Console.WriteLine( $"message has been published {messageStatus.MessageId}"); 
   },
   fault =>
   {
     Console.WriteLine( $"error {fault.Message}");
   } 
);

PublishOptions publishOptions = new PublishOptions();
publishOptions.AddHeader( "city", "Dallas" );
publishOptions.AddHeader( "state", "Texas" );
publishOptions.AddHeader( "temperature", 62 );

string message = "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%."
Backendless.Messaging.Publish( message,
                               "demo",
                               publishOptions,
                               callback );

String message = "Thunderstorms likely. High 62F. Winds NNW at 10 to 15 mph. Chance of rain 90%.";
PublishOptions publishOptions = new PublishOptions();
publishOptions.headers = {
  "city": "Dallas", 
  "state": "Texas", 
  "temperature": "62"
};
Backendless.messaging.publish(message, 
                              channelName: "demo", 
                              publishOptions: publishOptions)
.then((response) {
  print("Message has been published");
});

Codeless Reference

where:

Argument	Description
channel name	Name of the channel where a message must be published to.
subtopic name	The subtopic of the message allows developers to designate and filter messages by subtopic name. For instance, if a messaging application has a group and a few subgroups, all messages sent to the main group can be marked with this subtopic name which can be used to route messages to the appropriate subgroups depending on the context.
message	The contents of the message that must be published to a channel.
headers	Message headers is a collection of name/value pairs. A subscriber can set a filter expressed as an SQL "where clause" query (called selector) which Backendless uses to determine whether a message should be delivered to the subscriber. When the query matches the published data in message headers, message is delivered to the corresponding subscriber. For more information see the Conditional Delivery section of this guide.
publish at	Must be a Unix Timestamp, which is the number of milliseconds since the Epoch (January 1st, 1970 at UTC).  Note that if you want to specify the number of seconds instead of milliseconds, you must multiply the number by 1000 or add three trailing zeroes to your number (e.g. (1681324179 * 1000) or 1681324179000.
return result	When this box is checked, the operation returns an object containing the status of the message delivery and a unique message identifier.

Returns an object containing the status of the message delivery and a unique message identifier:

// Sample object  

{  
    "errorMessage":null,  
    "messageId":"message:FCBD8BF1-A45D-4564-B449-3C91D4896987",  
    "status":"published"  
}

The example below publishes the message to the "demo" channel. The headers property contains an object whose purpose is to allow listeners to filter this message if the "where clause" condition(selector property) is met on the listener side.