Databases are common tools for storing and organizing data. Databases are also very scalable in terms of performance and the amount of data that can be stored. Often an application will require the use of a database, and FlashCom cannot access a database without Flash Remoting.

RecordSet is a special custom class available in the NetServices package. The RecordSet class represents the query results from a database. Using RecordSet provides many methods to access query results and control how the results (known as a recordset or result set) are returned from the server. The remote server can interface directly with a database by executing either SQL code or stored procedures. The server returns the query results back to the client (in this case, FlashCom). In the FlashCom application, the results can be constructed into an instance of the RecordSet class as shown in Example 11-4.

load("netservices.asc");

application.onAppStart = function ( ) {
  NetServices.setDefaultGatewayUrl("http://www.myhost.com/flashservices/gateway");
  var conn = NetServices.createGatewayConnection( );
  var dataService = conn.getService(
                     "com.oreilly.pfcs.chapter11.PlayListService");

  var response = new Object( );
  response.onResult = function (result) {
    application.playList = result; // Save the playlist to a persistent scope
    application.outStream = Stream.get("radiochannel"); // Get a live stream

    var l = result.getLength( );                    // Get the recordset length
    for (var i = 0; i < l; i++) {
      var record = result.getItemAt(i);
      // Use the filename from the recordset.
      application.outStream.play(record.filename, 
        record.starttime,                  // Get the start time from the recordset
        record.length,                     // Get the length from the recordset
        false);                            // Add each record to the playlist
    }
  };
  response.onStatus = function (info) {
    trace("The PlayListService is unavailable right now");
    for (var i in info) trace(i + " : " + info[i]);
  };
  // Invoke the method to retrieve the recordset.
  dataService.GetPlayList( );
};

Example 11-4 assumes that a database table stores the following columns: name, filename, starttime, and length. It uses remoting to retrieve the list of tracks to play and builds a server-side playlist with the Stream object. This example also shows one simple way to interact with recordset data in your application. The most commonly used methods of the RecordSet class are getLength( ) and getItemAt( ). The getLength( ) method counts the number of records returned by the remoting service, which you can use to loop through the results. The getItemAt( ) method returns the record at the specified index (zero-relative). The returned record is an object with the database columns as the properties. You can retrieve a list of the column names returned by the query with the getColumnNames( ) method. This method returns an array of strings that correspond to the column names.

The results from the server can be broken up into smaller batches and distributed to the client in several ways, as controlled by the RecordSet.setDeliveryMode( ) method. The three modes are "ondemand", "fetchall", and "page". By default, recordsets operate in fetchall mode, in which all of the results are returned in a single batch. Pageable recordsets can be sent entirely in one batch, sent in multiple smaller batches, or stored on the server until the desired record is requested. For many scenarios, using pageable recordsets is not necessary. Often there are other solutions to limit the amount of data that needs to be displayed. However, there are times when the amount of data is just too large to transfer and display at once.

You can enable recordset paging in ondemand mode by passing a pagesize property in the parameters object when you call the remote method:

params = new Object(  );
params.pagesize = 5;
my_service.getData(params);