Tuning performance with digests

The UP.Link platform supports a multipart MIME format, called a digest, which allows you to send one or more entities--that is, WML decks and the other content types listed on page 54--in a single message to the UP.Link Server. This enables you to optimize use of the wireless network and make your service's user interface appear more responsive to the user.

If you know that the user will request multiple entities, you can send them all in a single response, instead of sending them individually as the user requests them. Because each HTTP request-response cycle involves a minimum time overhead regardless of the amount of data transmitted, sending a single response is normally much more efficient than sending multiple responses.

---

UP.Link digest format

The digest follows the standard multipart MIME format. The following is a high-level view of the format:

Digest header

Boundary
Content entity
Boundary
Content entity
Boundary
...

Each content entity must include the required Content-type header. To be referenced by another entity, a content entity must also include a Content-location header. The Content-location header must specify a URL relative to the digest URL.

For example, Figure 3-1 illustrates a simple digest containing two WML decks. Note that when the user navigates from deck1 to deck2, the UP.Phone does not need to issue another request to the UP.Link Server. It simply retrieves it from the digest which is already in memory. This improves the performance when the user navigates between the decks.

Figure  3-1.     A digest containing two decks

The UP.SDK provides Perl, COM, and C (Solaris only) libraries that make it easy to generate digests. The following sections describe how to use these libraries.

Generating a digest with the Perl libraries

To generate a digest with the UP.SDK Perl libraries, you follow these general steps:

1. Include the Digest.pm and DeckUtils.pl libraries in your code. The libraries are provided in sdk_installdir/examples/apputils.
2. Use the new() method to create a digest.
3. Add decks and other entities to the digest. For example, to add a deck, use the addDeck() method; to add a cache operation, use addCacheOp().
4. Use the OutputDigest() function to output the digest to standard output.

For example, the following Perl code generates the digest shown in Figure 3-1:

#! /usr/local/bin/perl5.001

# Sample libraries path (sdk_dir/examples/apputils)
BEGIN { push (@INC, "../apputils"); }
require Digest;
require DeckUtils.pl;


# Define two wml decks

$deck1 = <wml>
'<card>
'<do type="accept">
'<go href="?ns=deck2"/>
'</do>
'<p>
'This is a deck
'</p>
'</card>
'</wml>;
$deck2 = <wml>
'<card>
'<do type="accept">
'<go href="?ns=deck1"/>
'</do>
'This is another deck
'</card>
'</wml>;


# Create the digest

my $digest = new Digest;


# Add decks to the digest along with their content locations

$digest->addDeck("?ns=deck1", $deck1);
$digest->addDeck("?ns=deck2", $deck2);


# Output the digest

&AppUtils::OutputDigest($digest->asString());

Generating a digest with the C library

To generate a digest with the UP.SDK C digest library, follow these general steps:

1. Include the digest.h header file in your code. The header file and the associated object files are provided in sdk_installdir/examples/source/digests.
2. Use the DigestConstruct() method to create a digest.
3. Add decks and other entities to the digest. For example, to add a deck, use the DigestAddDeck() function.
4. Use the DigestSerialize() function to formulate the digest as a multipart MIME response and store it to a buffer.
5. Print the buffer containing the serialized digest.
6. Free the buffer and call DigestDestruct() to destroy the digest.

When you compile and link your code, you must compile the digest.c file. The sdk_installdir/examples/source/digests directory includes a sample file (test1.c) and makefiles for Solaris SPARCworks/ProWorks (Makefile) and Visual C++ (test1.mak) that demonstrate how to use the library.

The following C code generates the digest shown in Figure 3-1:

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "digest.h" /* from examples/source/digests */

main ()
{
    Digest d;
    char *output;

    /* Create the Digest object */
    d = DigestConstruct();

    /* Add decks to digest object with content locations */
    DigestAddDeck(d, "?ns=deck1", "<wml><card>"
        "<do type='accept'><go href='?ns=deck2'/></do><p>"
        "This is a deck</p></card></wml>");
    DigestAddDeck(d, "?ns=deck2", "<wml><card>"
        "<do type='accept'><go href='?ns=deck1'/></do>"
        "This is another deck</card></wml>");

    /* Create MIME multipart message as HTTP response */
    output = DigestSerialize(d);
    printf("%s",output);

    /* Free the output buffer and destroy Digest object */
    free(output);
    DigestDestruct(d);
}