### HTTP Source Data Set

#### Description

The Spry.Data.HTTPSourceDataSet class dervies from the base DataSet class. The HTTPSourceDataSet is an abstract class that provides the functionality necessary to load and cache data via the XMLHttpRequest object. It is not meant to be instantiated directly. Instead, other classes derive from it and override specific HTTPSourceDataSet methods to load and process a specific data format. The XMLDataSet and JSONDataSet classes are two examples of classes that derive from the HTTPSourceDataSet.

#### File

SpryData.js

#### Inheritance

Notifier -->DataSet --> HTTPSourceDataSet

### HTTPSourceDataSet constructor

#### Description

Spry.Data.HTTPSourceDataSet is the constructor function for the HTTP Source Data Set.

#### Format

Spry.Data.HTTPSourceDataSet(url, options)

#### Arguments

- url - The URL to the data to be loaded. This URL can be absolute, or relative to the HTML document that created the data set.
- options - An optional argument which if specified, must be an object with the option names as properties with values. Properties that can be specified are:
  - useCache - Boolean. If true attempts to retrieve the requested data from the internal HTTPSourceDataSet cache before hitting the server. If false, it bypasses the cache and makes a request for the data from the server. If not specified, the default is true.

#### Returns

N/A

#### Example

    // An example of a class that derives from the HTTPSourceDataSet:

    Spry.Data.XMLDataSet = function(url, xpath, options)

    {
      ...

      Spry.Data.HTTPSourceDataSet.call(this, url, options);

      ...
    }

      Spry.Data.XMLDataSet.prototype = new Spry.Data.HTTPSourceDataSet();
      Spry.Data.XMLDataSet.prototype.constructor = Spry.Data.XMLDataSet;

#### Sample

N/A

### getURL

#### Description

This function returns the current URL.

#### Format

getURL()

#### Arguments

N/A

#### Returns

String or null. Returns the URL that will be used to fetch the data. This may also return a null if one is not present.

#### Example

    var url = ds.getURL();

### loadDataIntoDataSet

#### Description

This function must be overwritten by the derived class. The function is meant to take the raw data from the HTTPRequest object and translate it into the internal row/column tabular structure expected by the data set. This function is not meant to be called directly by developers.

#### Format

loadDataIntoDataSet(rawDataDoc)

#### Arguments

rawDataDoc - The data received from the server. The format of the rawDataDoc is not defined. It is up to the derived class to deal with the data format.

#### Returns

N/A

#### Example

    ds.loadDataIntoDocument(rawdata);

### sessionExpiredChecker

#### Description

This function is called automatically by the HTTPSourceDataSet's internal mechanism and is intended as a hook for derived classes and developers so they can figure out if the data they recieved from the server was real data, or a message from the server stating that the user's session has expired. Classes that derive from HTTPSourceDataSet should override this method so they can analyze the data

#### Format

sessionExpiredChecker(req);

#### Arguments

req - Object. An instance of a Spry.URL.loadURL.Request object.

#### Returns

Boolean. true if the server session has expired. false if ok to proceed.

#### Example

    // The default implementation of sessionExpiredChecker looks like this:

    Spry.Data.HTTPSourceDataSet.prototype.sessionExpiredChecker = function(req)
    {
      if (req.xhRequest.responseText == 'session expired')
        return true;
      return false;
    };

#### Sample

N/A

### setSessionExpiredChecker

#### Description

This function allows the caller to dynamically change the sessionExpiredChecker function.

The function passed in must have the following interface:

    function mySessionChecker(req)
    {
      var sessionDidExpire = false;

      ...

      // Code to check the data from the server.
      // The data can be found in: req.xhRequest.responseText

      ...

      return sessionDidExpire;
    }

#### Format

setSessionExpiredChecker(sessionExpiredCheckerFunc);

#### Arguments

sessionExpiredCheckerFunc - Function Reference. The function to use to determine if the server response is a session expired message.

#### Returns

Boolean. true if the session has expired. false if it is ok to proceed with normal processing.

#### Example

    function mySessionExpiredChecker(req)
    {
      return /^\s*session expired: please login\s*$/.test(req.xhRequest.responseText);
    }

    ds.setSessionExpiredChecker(mySessionExpiredChecker);

#### Samples

N/A

### setDataFromDoc

#### Description

This function allows the developer to pass in an in-memory copy of the raw data for processing. It calls loadDataIntoDataSet() internally to process/flatten the data. It is also called by the HTTPSourceDataSet to process data received from the server.

#### Format

setDataFromDoc(rawDataDoc)

#### Arguments

rawDataDoc - The exact format of the data is unknown to the HTTPSourceDataSet. Derived classes define and override methods on the HTTPSourceDataSet so that it can process the data.

#### Returns

N/A

#### Example

    // An example of calling the setDataFromDoc method, on the
    // JSON Data Set, with a raw JSON string for processing.

    var ds = new Spry.Data.JSONDataSet(null);

    ...

    ds.setDataFromDoc("{ msg: 'hello world' }");

### setURL

#### Description

Change the URL to the data for the data set. This method does not load the data into the data set, it merely sets the internal URL and clears the data inside the data set, in preparation for loading. The developer must call loadData() to actually trigger the data loading.

#### Format

setURL(url, options);

#### Arguments

url - String. The URL to the data.

options - Object. This argument is optional. Possible option properties:

- headers
- method - "GET" or "POST"
- password
- postData
- username

#### Returns

N/A

#### Example

    var ds = new Spry.Data.XMLDataSet("foo.xml", "/foo/bar");

    ...
    ds.setURL("bar.php", { method: "POST", postData: "name1=foo&name22=bar", headers: {  "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" });
    ds.loadData();

### xhRequestProcessor

#### Description

This function is called automatically by the HTTPSourceDataSet upon receiving a response from the server. The purpose of this function is to extract out the data from the response from the server and return it in the format the derived data set expects to process. The default implementation of this function returns the responseText field of the XMLHttpRequest object. If the derived data set expects to extract the data from some other field of the XMLHttpRequest object, for example the responseXML, or must do some preprocessing so that the data is in some other format, it must override this method.

#### Format

xhRequestProcessor(xhreq);

#### Arguments

xhreq - Object. The Browser's native XMLHttpRequest object.

#### Returns

By default, returns a string that is the responseText field of the XMLHttpRequest object. Classes that override this method may return other types of values.

#### Example

    // The default implementation of xhRequestProcessor:

    Spry.Data.HTTPSourceDataSet.prototype.xhRequestProcessor = function(xhRequest)
    {
    	// This method needs to be overwritten by the descendent classes if other objects (like responseXML)
    	// are going to be used as a data source
    	// This implementation returns the responseText from xhRequest

    	var resp = xhRequest.responseText;

    	if (xhRequest.status == 200 || xhRequest.status == 0)
    		return resp;
    	return null;
    };

Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.