API: datasource YAHOO.util.DataSourceBase (YUI Library)

# Yahoo! UI Library

### DataSource Utility 2.8.1

Yahoo! UI Library > datasource > YAHOO.util.DataSourceBase
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.DataSourceBase

Known Subclasses:
  YAHOO.util.LocalDataSource YAHOO.util.XHRDataSource YAHOO.util.FunctionDataSource YAHOO.util.ScriptNodeDataSource

Base class for the YUI DataSource utility.

### Constructor

YAHOO.util.DataSourceBase `( oLiveData , oConfigs )`

Parameters:
  `oLiveData <HTMLElement>` Pointer to live data.
  `oConfigs <object>` (optional) Object literal of configuration values.

### Properties

#### _aCache - `private Object[]`

Local cache of data result object literals indexed chronologically.

#### _aIntervals - `private Array`

Array of polling interval IDs that have been enabled, needed to clear all intervals.

#### _oQueue - `private Object`

Local queue of request connections, enabled if queue needs to be managed.

#### _sName - `private String`

Name of DataSource instance.

#### DataSource.Parser - `static Object`

Data parsing functions.

#### DataSourceBase._nIndex - `private static Number`

Internal class variable to index multiple DataSource instances.

#### DataSourceBase._nTransactionId - `private static Number`

Internal class variable to assign unique transaction IDs.

#### dataType - `Number`

Where the live data is held:

TYPE_UNKNOWN
TYPE_LOCAL
TYPE_XHR
TYPE_SCRIPTNODE
TYPE_JSFUNCTION

Default Value: YAHOO.util.DataSourceBase.TYPE_UNKNOWN

#### ERROR_DATAINVALID - `final String`

Error message for invalid dataresponses.
Default Value: "Invalid data"

#### ERROR_DATANULL - `final String`

Error message for null data responses.
Default Value: "Null data"

#### liveData - `Object`

Pointer to live database.

#### maxCacheEntries - `Number`

Max size of the local cache. Set to 0 to turn off caching. Caching is useful to reduce the number of server connections. Recommended only for data sources that return comprehensive results for queries or when stale data is not an issue.
Default Value: 0

#### parseJSONArgs - `{MIXED|Array} If an Array, contents are used as individual arguments. Otherwise, value is used as an additional argument.`

Additional arguments passed to the JSON parse routine. The JSON string is the assumed first argument (where applicable). This property is not set by default, but the parse methods will use it if present.

#### responseSchema - `Object`

Response schema object literal takes a combination of the following properties:

resultsList
  Pointer to array of tabular data
resultNode
  Pointer to node name of row data (XML data only)
recordDelim
  Record delimiter (text data only)
fieldDelim
  Field delimiter (text data only)
fields
  Array of field names (aka keys), or array of object literals such as: {key:"fieldname",parser:YAHOO.util.DataSourceBase.parseDate}
metaFields
  Object literal of keys to include in the oParsedResponse.meta collection
metaNode
  Name of the node under which to search for meta information in XML response data

#### responseType - `Number`

Format of response:

TYPE_UNKNOWN
TYPE_JSARRAY
TYPE_JSON
TYPE_XML
TYPE_TEXT
TYPE_HTMLTABLE

Default Value: YAHOO.util.DataSourceBase.TYPE_UNKNOWN

#### TYPE_HTMLTABLE - `final Number`

Type is an HTML TABLE element. Data is parsed out of TR elements from all TBODY elements.
Default Value: 6

#### TYPE_JSARRAY - `final Number`

Type is a JavaScript Array.
Default Value: 0

#### TYPE_JSFUNCTION - `final Number`

Type is a JavaScript Function.
Default Value: 1

#### TYPE_JSON - `final Number`

Type is JSON.
Default Value: 3

#### TYPE_LOCAL - `final Number`

Type is local.
Default Value: 8

#### TYPE_SCRIPTNODE - `final Number`

Type is hosted on a server via a dynamic script node.
Default Value: 7

#### TYPE_TEXT - `final Number`

Type is plain text.
Default Value: 5

#### TYPE_UNKNOWN - `final Number`

Type is unknown.
Default Value: -1

#### TYPE_XHR - `final Number`

Type is hosted on a server via an XHR connection.
Default Value: 2

#### TYPE_XML - `final Number`

Type is XML.
Default Value: 4

#### useXPath - `Boolean`

When working with XML data, setting this property to true enables support for XPath-syntaxed locators in schema definitions.
Default Value: false

### Methods

#### _getLocationValue

`private static Object _getLocationValue ( field , context )`
Get an XPath-specified value for a given field from an XML node or document.

Parameters:
  `field <String | Object>` Field definition.
  `context <Object>` XML node or document to search within.

Returns: `Object`
  Data value or null.

#### addToCache

`void addToCache ( oRequest , oResponse )`
Adds a new item to the cache. If cache is full, evicts the stalest item before adding the new item.

Parameters:
  `oRequest <Object>` Request object.
  `oResponse <Object>` Response object to cache.

#### clearAllIntervals

`void clearAllIntervals ( )`
Disables all known polling intervals.

#### clearInterval

`void clearInterval ( nId )`
Disables polling mechanism associated with the given interval ID.

Parameters:
  `nId <Number>` Interval ID.

#### DataSourceBase.parseDate

`static Date DataSourceBase.parseDate ( oData )`
Converts data to type Date.

Parameters:
  `oData <Date | String | Number>` Data to convert.

Returns: `Date`
  A Date instance.

#### DataSourceBase.parseNumber

`static Number DataSourceBase.parseNumber ( oData )`
Converts data to type Number.

Parameters:
  `oData <String | Number | Boolean>` Data to convert. Note, the following values return as null: null, undefined, NaN, "".

Returns: `Number`
  A number, or null.

#### DataSourceBase.parseString

`static String DataSourceBase.parseString ( oData )`
Converts data to type String.

Parameters:
  `oData <String | Number | Boolean | Date | Array | Object>` Data to parse. The special values null and undefined will return null.

Returns: `String`
  A string, or null.

#### doBeforeCallback

`Object doBeforeCallback ( oRequest , oFullResponse , oParsedResponse , oCallback )`
Overridable method gives implementers access to the original full response and the parsed response (parsed against the given schema) before the data is added to the cache (if applicable) and then sent back to callback function. This is your chance to access the raw response and/or populate the parsed response with any custom data.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full response from the live database.
  `oParsedResponse <Object>` The parsed response to return to calling object.
  `oCallback <Object>` The callback object.

Returns: `Object`
  Parsed response object.

#### doBeforeParseData

`Object doBeforeParseData ( oRequest , oFullResponse , oCallback )`
Overridable method gives implementers access to the original full response before the data gets parsed. Implementers should take care not to return an unparsable or otherwise invalid response.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full response from the live database.
  `oCallback <Object>` The callback object.

Returns: `Object`
  Full response for parsing.

#### flushCache

`void flushCache ( )`
Flushes cache.

#### getCachedResponse

`Object getCachedResponse ( oRequest , oCallback , oCaller )`
Overridable method passes request to cache and returns cached response if any, refreshing the hit in the cache as the newest item. Returns null if there is no cache hit.

Parameters:
  `oRequest <Object>` Request object.
  `oCallback <Object>` Callback object.
  `oCaller <Object>` (deprecated) Use callback object.

Returns: `Object`
  Cached response object or null.

#### handleResponse

`void handleResponse ( oRequest , oRawResponse , oCallback , oCaller , tId )`
Receives raw data response and type converts to XML, JSON, etc as necessary. Forwards oFullResponse to appropriate parsing function to get turned into oParsedResponse. Calls doBeforeCallback() and adds oParsedResponse to the cache when appropriate before calling issueCallback(). The oParsedResponse object literal has the following properties:

tId {Number}
Unique transaction ID
results {Array}
Array of parsed data results
meta {Object}
Object literal of meta values
error {Boolean}
(optional) True if there was an error
cached {Boolean}
(optional) True if response was cached

Parameters:
  `oRequest <Object>` Request object
  `oRawResponse <Object>` The raw response from the live database.
  `oCallback <Object>` Callback object literal.
  `oCaller <Object>` (deprecated) Use oCallback.scope.
  `tId <Number>` Transaction ID.

#### isCacheHit

`Boolean isCacheHit ( oRequest , oCachedRequest )`
Default overridable method matches given request to given cached request. Returns true if is a hit, returns false otherwise. Implementers should override this method to customize the cache-matching algorithm.

Parameters:
  `oRequest <Object>` Request object.
  `oCachedRequest <Object>` Cached request object.

Returns: `Boolean`
  True if given request matches cached request, false otherwise.

#### issueCallback

`static void issueCallback ( callback , params , error , scope )`
Executes a configured callback. For object literal callbacks, the third param determines whether to execute the success handler or failure handler.

Parameters:
  `callback <Function|Object>` the callback to execute
  `params <Array>` params to be passed to the callback method
  `error <Boolean>` whether an error occurred
  `scope <Object>` the scope from which to execute the callback (deprecated - use an object literal callback)

#### makeConnection

`Number makeConnection ( oRequest , oCallback , oCaller )`
Overridable default method generates a unique transaction ID and passes the live data reference directly to the handleResponse function. This method should be implemented by subclasses to achieve more complex behavior or to access remote data.

Parameters:
  `oRequest <Object>` Request object.
  `oCallback <Object>` Callback object literal.
  `oCaller <Object>` (deprecated) Use oCallback.scope.

Returns: `Number`
  Transaction ID.

#### parseArrayData

`Object parseArrayData ( oRequest , oFullResponse )`
Overridable method parses Array data into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full Array from the live database.

Returns: `Object`
  Parsed response object with the following properties:
  - results (Array) Array of parsed data results
  - error (Boolean) True if there was an error

#### parseData

`Object} Parsed response object with the following properties:
- results {Array} Array of parsed data results
- meta {Object} Object literal of meta values
- error {Boolean parseData ( oRequest , oFullResponse )`
Overridable method parses data of generic RESPONSE_TYPE into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full Array from the live database.

Returns: `Object} Parsed response object with the following properties:
- results {Array} Array of parsed data results
- meta {Object} Object literal of meta values
- error {Boolean`
  (optional) True if there was an error

#### parseHTMLTableData

`Object parseHTMLTableData ( oRequest , oFullResponse )`
Overridable method parses an HTML TABLE element reference into a response object. Data is parsed out of TR elements from all TBODY elements.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full HTML element reference from the live database.

Returns: `Object`
  Parsed response object with the following properties
  - results (Array) Array of parsed data results
  - error (Boolean) True if there was an error

#### parseJSONData

`Object parseJSONData ( oRequest , oFullResponse )`
Overridable method parses JSON data into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full JSON from the live database.

Returns: `Object`
  Parsed response object with the following properties
  - results (Array) Array of parsed data results
  - error (Boolean) True if there was an error

#### parseTextData

`Object parseTextData ( oRequest , oFullResponse )`
Overridable method parses plain text data into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full text response from the live database.

Returns: `Object`
  Parsed response object with the following properties:
  - results (Array) Array of parsed data results
  - error (Boolean) True if there was an error

#### parseXMLData

`Object parseXMLData ( oRequest , oFullResponse )`
Overridable method parses XML data into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oFullResponse <Object>` The full XML response from the live database.

Returns: `Object`
  Parsed response object with the following properties
  - results (Array) Array of parsed data results
  - error (Boolean) True if there was an error

#### parseXMLResult

`Object parseXMLResult ( result )`
Overridable method parses XML data for one result into an object literal.

Parameters:
  `result <XML>` XML for one result.

Returns: `Object`
  Object literal of data for one result.

#### sendRequest

`Number sendRequest ( oRequest , oCallback , oCaller )`
First looks for cached response, then sends request to live data. The following arguments are passed to the callback function:

`oRequest`
  The same value that was passed in as the first argument to sendRequest.
`oParsedResponse`
  An object literal containing the following properties:
  `tId`
    Unique transaction ID number.
  `results`
    Schema-parsed data results.
  `error`
    True in cases of data error.
  `cached`
    True when response is returned from DataSource cache.
  `meta`
    Schema-parsed meta data.
`oPayload`
  The same value as was passed in as `argument` in the oCallback object literal.

Parameters:
  `oRequest <Object>` Request object.
  `oCallback <Object>` An object literal with the following properties:
  `success`
    The function to call when the data is ready.
  `failure`
    The function to call upon a response failure condition.
  `scope`
    The object to serve as the scope for the success and failure handlers.
  `argument`
    Arbitrary data that will be passed back to the success and failure handlers.
  `oCaller <Object>` (deprecated) Use oCallback.scope.

Returns: `Number`
  Transaction ID, or null if response found in cache.

#### setInterval

`Number setInterval ( nMsec , oRequest , oCallback , oCaller )`
Sets up a polling mechanism to send requests at set intervals and forward responses to given callback.

Parameters:
  `nMsec <Number>` Length of interval in milliseconds.
  `oRequest <Object>` Request object.
  `oCallback <Function>` Handler function to receive the response.
  `oCaller <Object>` (deprecated) Use oCallback.scope.

Returns: `Number`
  Interval ID.

#### toString

`String toString ( )`
Public accessor to the unique name of the DataSource instance.

Returns: `String`
  Unique name of the DataSource instance.

### Events

#### cacheFlushEvent

`cacheFlushEvent ( )`
Fired when the local cache is flushed.

#### cacheRequestEvent

`cacheRequestEvent ( oArgs.request , oArgs.callback , oArgs.caller )`
Fired when a request is made to the local cache.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

#### cacheResponseEvent

`cacheResponseEvent ( oArgs.request , oArgs.response , oArgs.callback , oArgs.caller )`
Fired when data is retrieved from the local cache.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.response <Object>` The response object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

#### dataErrorEvent

`dataErrorEvent ( oArgs.request , oArgs.response , oArgs.callback , oArgs.caller , oArgs.message )`
Fired when an error is encountered with the live data source.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.response <String>` The response object (if available).
  `oArgs.callback <Object>` The callback object.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.
  `oArgs.message <String>` The error message.

#### requestEvent

`requestEvent ( oArgs.request , oArgs.callback , oArgs.tId , oArgs.caller )`
Fired when a request is sent to the live data source.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.tId <Number>` Transaction ID.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

#### responseCacheEvent

`responseCacheEvent ( oArgs.request , oArgs.response , oArgs.callback , oArgs.caller )`
Fired when response is cached.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.response <Object>` The parsed response object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

#### responseEvent

`responseEvent ( oArgs.request , oArgs.response , oArgs.callback , oArgs.tId , oArgs.caller )`
Fired when live data source sends response.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.response <Object>` The raw response object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.tId <Number>` Transaction ID.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

#### responseParseEvent

`responseParseEvent ( oArgs.request , oArgs.response , oArgs.callback , oArgs.caller )`
Fired when response is parsed.

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.response <Object>` The parsed response object.
  `oArgs.callback <Object>` The callback object.
  `oArgs.caller <Object>` (deprecated) Use callback.scope.

Copyright © 2010 Yahoo! Inc. All rights reserved.