API: datasource DataSource (YUI Library)

# Yahoo! UI Library

### DataSource Utility 2.2.2

Yahoo! UI Library > datasource > DataSource

## Class DataSource - uses YAHOO.util.EventProvider

The DataSource class defines and manages a live set of data for widgets to interact with. Examples of live databases include in-memory local data such as a JavaScript array, a JavaScript function, or JSON, or remote data such as data retrieved through an XHR connection.

### Constructor

DataSource `( oLiveData , oConfigs )`

Parameters:
  `oLiveData <Object>` Pointer to live database
  `oConfigs <Object>` (optional) Object literal of configuration values

### Properties

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

Local cache of data result objects indexed chronologically.

#### _nIndex `- private Number`

Internal class variable to index multiple DataSource instances.

#### _sName `- private String`

Name of DataSource instance.

#### _xhrCallback `- private object`

Connection Manager callback object

#### connMgr `- Object`

Alias to YUI Connection Manager. Allows implementers to specify their own subclasses of the YUI Connection Manager utility.
Default Value: YAHOO.util.Connect

#### connTimeout `- Number`

If data is accessed over XHR via Connection Manager, the connection timeout is configurable in milliseconds the XHR connection will wait for a server response. A a value of zero indicates the XHR connection will wait forever. Any value greater than zero will use the Connection utility's Auto-Abort feature.
Default Value: 0

#### dataType `- Number`

Where the live data is held.
Default Value: YAHOO.util.DataSource.TYPE_UNKNOWN

#### ERROR_DATAINVALID `- final String`

Error message for invalid data responses.
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

#### 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",converter:YAHOO.util.DataSource.convertDate}

#### responseType `- Number`

Format of response.
Default Value: YAHOO.util.DataSource.TYPE_UNKNOWN

#### 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_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

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _xhrFailure

`private void _xhrFailure ( oResponse )`
Connection Manager failure handler

Parameters:
  `oResponse <Object>` HTTPXMLRequest object

Returns: `void`

#### _xhrSuccess

`private void _xhrSuccess ( oResponse )`
Connection Manager success handler

Parameters:
  `oResponse <Object>` HTTPXMLRequest object

Returns: `void`

#### 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.

Returns: `void`

#### convertDate

`static Date convertDate ( )`
Converts data from String to Date objects.

Returns: `Date`
  Date object.

#### convertNumber

`static Number convertNumber ( )`
Converts data from String to Number objects.

Returns: `Number`
  Number object.

#### doBeforeCallback

`Object doBeforeCallback ( oRequest , oRawResponse , oParsedResponse )`
Overridable method gives implementers access to the original raw 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.
  `oRawResponse <Object>` The raw response from the live database.
  `oParsedResponse <Object>` The parsed response to return to calling object.

Returns: `Object`
  Parsed response object

#### flushCache

`void flushCache ( )`
Flushes cache.

Returns: `void`

#### 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 <Function>` Handler function to receive the response
  `oCaller <Object>` The Calling object that is making the request

Returns: `Object`
  Cached response object or null.

#### handleResponse

`void handleResponse ( oRequest , oRawResponse , oCallback , oCaller )`
Handles raw data response from live data source.

Parameters:
  `oRequest <Object>` Request object
  `oRawResponse <Object>` The raw response from the live database
  `oCallback <Function>` Handler function to receive the response
  `oCaller <Object>` The calling object that is making the request

Returns: `void`

#### 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.

#### makeConnection

`void makeConnection ( oRequest , oCallback , oCaller )`
Overridable method provides default functionality to make a connection to live data in order to send request. The response coming back is then forwarded to the handleResponse function. This method should be customized for more complex implementations.

Parameters:
  `oRequest <Object>` Request object.
  `oCallback <Function>` Handler function to receive the response
  `oCaller <Object>` The Calling object that is making the request

Returns: `void`

#### parseArrayData

`Object parseArrayData ( oRequest , oRawResponse )`
Overridable method parses raw array data into a response object.

Parameters:
  `oRequest <Object>` Request object.
  `oRawResponse <Object>` The raw response from the live database.

Returns: `Object`
  Parsed response object.

#### parseJSONData

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

Parameters:
  `oRequest <Object>` Request object
  `oRawResponse <Object>` The raw response from the live database

Returns: `Object`
  Parsed response object

#### parseTextData

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

Parameters:
  `oRequest <Object>` Request object
  `oRawResponse <Object>` The raw response from the live database

Returns: `Object`
  Parsed response object

#### parseXMLData

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

Parameters:
  `oRequest <Object>` Request object
  `oRawResponse <Object>` The raw response from the live database

Returns: `Object`
  Parsed response object

#### sendRequest

`void sendRequest ( oRequest , oCallback , oCaller )`
First looks for cached response, then sends request to live data.

Parameters:
  `oRequest <Object>` Request object
  `oCallback <Function>` Handler function to receive the response
  `oCaller <Object>` The Calling object that is making the request

Returns: `void`

#### toString

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

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

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### 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 <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

#### dataErrorEvent

`dataErrorEvent ( oArgs.request , 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.callback <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.
  `oArgs.message <String>` The error message.

#### getCachedResponseEvent

`getCachedResponseEvent ( 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 <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

#### requestEvent

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

Parameters:
  `oArgs.request <Object>` The request object.
  `oArgs.callback <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

#### 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 <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

#### responseEvent

`responseEvent ( oArgs.request , oArgs.response , oArgs.callback , 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 <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

#### 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 <Function>` The callback function.
  `oArgs.caller <Object>` The parent object of the callback function.

Copyright © 2007 Yahoo! Inc. All rights reserved.