State of the World

AMPS State of the World (SOW) allows you to automatically keep and query the latest information about a topic on the AMPS server, without building a separate database. Using SOW lets you build impressively high-performance applications that provide rich experiences to users. The AMPS C# client lets you query SOW topics and subscribe to changes with ease.

Performing SOW Queries

To begin, we will look at a simple example of issuing a SOW query.

public void ExecuteSOWQuery(Client client)
{

    foreach (Message m in client.sow("messages-sow", "/id > 20"))
    {
        if (m.Command == Message.Commands.BeginGroup)
        {
            System.Console.WriteLine("--- Begin SOW Results ---");
        }
        if (m.Command == Message.Commands.EndGroup)
        {
            System.Console.WriteLine("--- End SOW Results ---");
        }
        if (m.Command == Message.Commands.SOW)
        {
            System.Console.WriteLine(m.Data);
        }
    }
}

In the example above, the ExecuteSOWQuery() function invokes Client.sow() to initiate a SOW query on the messages-sow topic, for all entries that have an id greater than 20.

As the query executes, the body of the loop is invoked for each matching entry in the topic. Messages containing the data of matching entries have a Command of value sow; as those arrive, we write them to the console. AMPS sends a group_begin message at the beginning of the results and a group_end message at the end of the results. We use those messages to delimit the results of the query.

As with subscribe, the sow command also provides an asynchronous version, as well as versions that accept a Command. For example, the listing below shows an asynchronous SOW command that specifies the batch size, or the maximum number of records that AMPS will return at a time.

private void HandleSOW(Message message)
{
    if (message.Command == Message.Commands.SOW)
    {
        Console.WriteLine(message.Data);
    }
}

public void ExecuteSOWQuery(Client client)
{
    Command command = new Command(Message.Commands.SOW)
                             .setTopic("messages-sow")
                             .setFilter("/id > 20")
                             .setBatchSize(100);

    client.executeAsync(command, message => HandleSOW(message));

}

In the example above, the ExecuteSOWQuery() function invokes Client.executeAsync() to initiate a SOW query on the messages-sow topic, for all entries that have an id greater than 20. The SOW query is requested with a batch size of 100, meaning that AMPS will attempt to send 100 messages at a time as results are returned.

As the query executes, the HandleSOW() method is invoked for each matching entry in the topic. Messages containing the data of matching entries have a Command of value sow; as those arrive, we write them to the console.