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, HDML decks and the other content types listed in Valid content types--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. For a content entity to be referenced by another entity, it 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 HDML 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 and C 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 HDMLutils.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 addHDMLDeck() 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 'HDMLUtils.pl';

# Define two HDML decks with display cards.
$deck1 = '<HDML VERSION=3.0>'.
    '<DISPLAY>'.
    '<ACTION TYPE=ACCEPT TASK=GO DEST="?NS=DECK2">'.
    'This is deck1'.
    '</DISPLAY>'.
    '</HDML>';
$deck2 = '<HDML VERSION=3.0>'.
    '<DISPLAY>'.
    '<ACTION TYPE=ACCEPT TASK=GO DEST="?NS=DECK1">'.
    'This is deck2'.
    '</DISPLAY>'.
    '</HDML>';

# Create the digest
my $digest = new Digest;

# Add decks to the digest along with their content locations
$digest->addHDMLDeck("?NS=DECK1", $deck1);
$digest->addHDMLDeck("?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, you 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. Clean up by freeing the buffer and calling 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 along with content locations*/
  DigestAddDeck(d, "?NS=DECK1", "<HDML VERSION=3.0><DISPLAY> "
    "<ACTION TYPE=ACCEPT TASK=GO DEST=?NS=DECK2>"
    "This is deck1</DISPLAY></HDML>");
  DigestAddDeck(d, "?NS=DECK2", "<HDML VERSION=3.0><DISPLAY> "
    "<ACTION TYPE=ACCEPT TASK=GO DEST=?NS=DECK1>"
    "This is deck2</DISPLAY></HDML>");

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

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