Managing SOW Contents

AMPS allows applications to manage the contents of the SOW by explicitly deleting messages that are no longer relevant. For example, if a particular delivery van is retired from service, the application can remove the record for the van by deleting the record for the van.

The client provides the following methods for deleting records from the SOW:

• sow_delete - Accepts a topic and filter, and deletes all messages that match the filter from the topic specified.

• sow_delete_by_keys - Accepts a set of SOW keys as a comma-delimited string and deletes messages for those keys, regardless of the contents of the messages. SOW keys are provided in the header of a SOW message, and are the internal identifier AMPS uses for that SOW message.

• sow_delete_by_data - Accepts a topic and message, and deletes the SOW record that would be updated by that message.

The most efficient way to remove messages from the SOW is to use sow_delete_by_keys or sow_delete_by_data, since those options allow AMPS to exactly target the message or messages to be removed. Many applications use sow_delete, since this is the most flexible method for removing items from the SOW when the application does not have information on the exact messages to be removed.

In either case, AMPS sends an OOF message to all subscribers who have received updates for the messages removed, as described in the previous section.

The simple form of the sow_delete command returns a Message. This Message is an acknowledgment that contains information on the delete command. For example, the following snippet simply prints informational text with the number of messages deleted:

msg = client.sow_delete(
    "sow_topic",
    "/id IN (42, 64, 37)"
)

print("Got an %s message containing %s: deleted %s SOW entries" % \
      (msg.get_command(), msg.get_ack_type(), msg.get_matches()))

The sow_delete command also provides an asynchronous version that requires a message handler. This message handler is designed to receive sow_delete response messages from AMPS:

def delete_handler(m):
    print("Got an %s message containing %s: deleted %s SOW entries" % \
        (m.get_command(), m.get_ack_type(), m.get_matches()))

client.execute_async(
    Command("sow_delete")               \
    .set_topic("sow_topic")             \
    .set_filter("/id IN (42, 64, 37)")  \
    .add_ack_type("stats"),             \
    delete_handler
)

Acknowledging messages from a queue uses a form of the sow_delete command that is only supported for queues. Acknowledgment is discussed in the Using Queues chapter in this guide.