17.9. Raising Queueing events

According to the name, each new Queueing event joins the queue of previously received instances. This continues until the queue is full. Then each new event pushes the oldest one out of the queue. The event is also removed from the queue at the end of the lifetime. Event parameters are defined in the site structure. These are the event name, lifetime, maximum queue size, and access rule. See the section “Defining service events” for details. Queuing events are used when clients need all raised events.

There are no clear similarities between Softnet queuing events and MQTT topics. This is because MQTT topics cannot contain more than one message at a time. However, if a subscriber needs to receive all messages published on the MQTT topic while it is offline, the subscriber can create a stateful subscription.

Let’s recall how to define a Queueing event. To do this, the SiteStructure implementation has three overloaded methods that differ in the way access rules are defined. See the chapter “Access rule definition technique” for details. The following method defines a Queueing event without access restrictions:

void addQueueingEvent(String eventName, int lifeTime, int queueSize);

The first parameter takes the event name. The second parameter takes the event’s lifetime in seconds. And, the third parameter takes the queue size.

After the event is defined, it can be raised by the following method of the ServiceEndpoint class:

public void raiseEvent(QueueingEvent event)

The parameter is of type QueueingEvent with the following members:

public class QueueingEvent {
    public final String name;
    public final SequenceEncoder arguments;			
    public QueueingEvent(String name)
}

Here is a description of the QueueingEvent members:

  • name is the name of the event, provided to the constructor when the class instance is created, and also specified in the event definition in the site structure;
  • arguments is a field of type SequenceEncoder provided by Softnet ASN.1 Codec. Accordingly, on the client side, events have an arguments field of type SequenceDecoder. The data size in arguments is limited to 2 kilobytes;
  • QueueingEvent is a constructor that takes the name of the event.

This section concludes with an example of defining and raising a Queueing event.

  1. The following code defines “CriticalWaterTemperature” as a Queueing event using the second overload of the addQueueingEvent method. It specifies the lifetime as 10 hours, the maximum queue size as 50, and the access rule denies guest clients:
    siteStructure.addQueueingEvent(
    "CriticalWaterTemperature", // event name
    TimeSpan.fromHours(10),     // lifetime in seconds
    50,                         // maximum queue size
    GuestAccess.GuestDenied);   // guest is denied
  2. The next code instantiates the QueueingEvent class and populates the arguments field with a temperature value of 95 degrees Celsius, and raises the event:
    QueueingEvent event = new QueueingEvent("CriticalWaterTemperature");
event.arguments.Int32(95);
serviceEndpoint.raiseEvent(event);

TABLE OF CONTENTS