1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <title>API: datasource DataSource (YUI Library)
</title>
5 <link rel=
"stylesheet" type=
"text/css" href=
"assets/api.css">
9 <div id=
"doc3" class=
"yui-t2">
12 <h1>Yahoo! UI Library
</h1>
13 <h3>DataSource Utility
<span class=
"subtitle">2.2.0</span></h3>
15 <a href=
"./index.html">Yahoo! UI Library
</a>
16 > <a href=
"./module_datasource.html">datasource
</a>
32 Class
<b>DataSource
</b>
33 <span class=
"extends">
36 <span class=
"extends">
39 <a href=
"YAHOO.util.EventProvider.html">YAHOO.util.EventProvider
</a>
45 <!-- class tree goes here -->
50 <div class=
"summary description">
51 The DataSource class defines and manages a live set of data for widgets to
52 interact with. Examples of live databases include in-memory
53 local data such as a JavaScript array, a JavaScript function, or JSON, or
54 remote data such as data retrieved through an XHR connection.
57 <div class=
"section constructor details">
58 <h3><a name=
"constructor_detail">Constructor
</a></h3>
61 <strong>DataSource
</strong>
73 <div class=
"description">
80 Pointer to live database
86 (optional) Object literal of configuration values
96 <div class=
"section field details">
97 <h3><a name=
"field_detail">Properties
</a></h3>
99 <h4><a name=
"_aCache">_aCache
</a>
100 <code>- private Object[]
</code>
103 <div class=
"description">
104 Local cache of data result objects indexed chronologically.
112 <h4><a name=
"_nIndex">_nIndex
</a>
113 <code>- private Number
</code>
116 <div class=
"description">
117 Internal class variable to index multiple DataSource instances.
125 <h4><a name=
"_sName">_sName
</a>
126 <code>- private String
</code>
129 <div class=
"description">
130 Name of DataSource instance.
138 <h4><a name=
"_xhrCallback">_xhrCallback
</a>
139 <code>- private object
</code>
142 <div class=
"description">
143 Connection Manager callback object
151 <h4><a name=
"connMgr">connMgr
</a>
152 <code>- Object
</code>
155 <div class=
"description">
156 Alias to YUI Connection Manager. Allows implementers to specify their own
157 subclasses of the YUI Connection Manager utility.
162 <div class=
"default">
163 Default Value: YAHOO.util.Connect
168 <h4><a name=
"connTimeout">connTimeout
</a>
169 <code>- Number
</code>
172 <div class=
"description">
173 If data is accessed over XHR via Connection Manager, the connection timeout is
174 configurable in milliseconds the XHR connection will wait for a server
175 response. A a value of zero indicates the XHR connection will wait forever.
176 Any value greater than zero will use the Connection utility's Auto-Abort
182 <div class=
"default">
188 <h4><a name=
"dataType">dataType
</a>
189 <code>- Number
</code>
192 <div class=
"description">
193 Where the live data is held.
198 <div class=
"default">
199 Default Value: YAHOO.util.DataSource.TYPE_UNKNOWN
204 <h4><a name=
"ERROR_DATAINVALID">ERROR_DATAINVALID
</a>
205 <code>- final String
</code>
208 <div class=
"description">
209 Error message for invalid data responses.
214 <div class=
"default">
215 Default Value:
"Invalid data"
220 <h4><a name=
"ERROR_DATANULL">ERROR_DATANULL
</a>
221 <code>- final String
</code>
224 <div class=
"description">
225 Error message for null data responses.
230 <div class=
"default">
231 Default Value:
"Null data"
236 <h4><a name=
"liveData">liveData
</a>
237 <code>- Object
</code>
240 <div class=
"description">
241 Pointer to live database.
249 <h4><a name=
"maxCacheEntries">maxCacheEntries
</a>
250 <code>- Number
</code>
253 <div class=
"description">
254 Max size of the local cache. Set to
0 to turn off caching. Caching is
255 useful to reduce the number of server connections. Recommended only for data
256 sources that return comprehensive results for queries or when stale data is
262 <div class=
"default">
268 <h4><a name=
"responseType">responseType
</a>
269 <code>- Number
</code>
272 <div class=
"description">
278 <div class=
"default">
279 Default Value: YAHOO.util.DataSource.TYPE_UNKNOWN
284 <h4><a name=
"TYPE_JSARRAY">TYPE_JSARRAY
</a>
285 <code>- final Number
</code>
288 <div class=
"description">
289 Type is a JavaScript Array.
294 <div class=
"default">
300 <h4><a name=
"TYPE_JSFUNCTIOn">TYPE_JSFUNCTIOn
</a>
301 <code>- final Number
</code>
304 <div class=
"description">
305 Type is a JavaScript Function.
310 <div class=
"default">
316 <h4><a name=
"TYPE_JSON">TYPE_JSON
</a>
317 <code>- final Number
</code>
320 <div class=
"description">
326 <div class=
"default">
332 <h4><a name=
"TYPE_TEXT">TYPE_TEXT
</a>
333 <code>- final Number
</code>
336 <div class=
"description">
342 <div class=
"default">
348 <h4><a name=
"TYPE_UNKNOWN">TYPE_UNKNOWN
</a>
349 <code>- final Number
</code>
352 <div class=
"description">
358 <div class=
"default">
364 <h4><a name=
"TYPE_XHR">TYPE_XHR
</a>
365 <code>- final Number
</code>
368 <div class=
"description">
369 Type is hosted on a server via an XHR connection.
374 <div class=
"default">
380 <h4><a name=
"TYPE_XML">TYPE_XML
</a>
381 <code>- final Number
</code>
384 <div class=
"description">
390 <div class=
"default">
401 <div class=
"section field inheritance">
402 <h4>Properties inherited from
<a href=
"YAHOO.util.EventProvider.html">YAHOO.util.EventProvider
</a>:
</h4>
403 <div class=
"content">
406 <a href=
"YAHOO.util.EventProvider.html#__yui_events">__yui_events
</a>,
407 <a href=
"YAHOO.util.EventProvider.html#__yui_subscribers">__yui_subscribers
</a>
412 <div class=
"section method details">
413 <h3><a name=
"methodDetails">Methods
</a></h3>
414 <div class=
"content">
416 <a name=
"_xhrFailure">_xhrFailure
</a></h4>
423 <strong>_xhrFailure
</strong>
433 <div class=
"description">
434 Connection Manager failure handler
437 <div class=
"description">
442 <code>oResponse
<Object
></code>
443 HTTPXMLRequest object
460 <a name=
"_xhrSuccess">_xhrSuccess
</a></h4>
467 <strong>_xhrSuccess
</strong>
477 <div class=
"description">
478 Connection Manager success handler
481 <div class=
"description">
486 <code>oResponse
<Object
></code>
487 HTTPXMLRequest object
504 <a name=
"addToCache">addToCache
</a></h4>
511 <strong>addToCache
</strong>
525 <div class=
"description">
526 Adds a new item to the cache. If cache is full, evicts the stalest item
527 before adding the new item.
530 <div class=
"description">
535 <code>oRequest
<Object
></code>
539 <code>oResponse
<Object
></code>
540 Response object to cache.
557 <a name=
"flushCache">flushCache
</a></h4>
564 <strong>flushCache
</strong>
569 <div class=
"description">
573 <div class=
"description">
589 <a name=
"getCachedResponse">getCachedResponse
</a></h4>
596 <strong>getCachedResponse
</strong>
614 <div class=
"description">
615 Overridable method passes request to cache and returns cached response if any,
616 refreshing the hit in the cache as the newest item. Returns null if there is
620 <div class=
"description">
625 <code>oRequest
<Object
></code>
629 <code>oCallback
<Function
></code>
630 Handler function to receive the response
633 <code>oCaller
<Object
></code>
634 The Calling object that is making the request
643 <dd>Cached response object or null.
</dd>
651 <a name=
"handleResponse">handleResponse
</a></h4>
658 <strong>handleResponse
</strong>
680 <div class=
"description">
681 Handles raw data response from live data source.
684 <div class=
"description">
689 <code>oRequest
<Object
></code>
693 <code>oRawResponse
<Object
></code>
694 The raw response from the live database
697 <code>oCallback
<Function
></code>
698 Handler function to receive the response
701 <code>oCaller
<Object
></code>
702 The calling object that is making the request
719 <a name=
"isCacheHit">isCacheHit
</a></h4>
726 <strong>isCacheHit
</strong>
740 <div class=
"description">
741 Default overridable method matches given request to given cached request.
742 Returns true if is a hit, returns false otherwise. Implementers should
743 override this method to customize the cache-matching algorithm.
746 <div class=
"description">
751 <code>oRequest
<Object
></code>
755 <code>oCachedRequest
<Object
></code>
756 Cached request object.
765 <dd>True if given request matches cached request, false otherwise.
</dd>
773 <a name=
"makeConnection">makeConnection
</a></h4>
780 <strong>makeConnection
</strong>
798 <div class=
"description">
799 Overridable method provides default functionality to make a connection to
800 live data in order to send request. The response coming back is then
801 forwarded to the handleResponse function. This method should be customized
802 for more complex implementations.
805 <div class=
"description">
810 <code>oRequest
<Object
></code>
814 <code>oCallback
<Function
></code>
815 Handler function to receive the response
818 <code>oCaller
<Object
></code>
819 The Calling object that is making the request
836 <a name=
"parseArrayData">parseArrayData
</a></h4>
843 <strong>parseArrayData
</strong>
857 <div class=
"description">
858 Overridable method parses raw array data into a response object.
861 <div class=
"description">
866 <code>oRequest
<Object
></code>
870 <code>oRawResponse
<Object
></code>
871 The raw response from the live database
880 <dd>Parsed response object
</dd>
888 <a name=
"parseJSONData">parseJSONData
</a></h4>
895 <strong>parseJSONData
</strong>
909 <div class=
"description">
910 Overridable method parses raw JSON data into a response object.
913 <div class=
"description">
918 <code>oRequest
<Object
></code>
922 <code>oRawResponse
<Object
></code>
923 The raw response from the live database
932 <dd>Parsed response object
</dd>
940 <a name=
"parseTextData">parseTextData
</a></h4>
947 <strong>parseTextData
</strong>
961 <div class=
"description">
962 Overridable method parses raw plain text data into a response object.
965 <div class=
"description">
970 <code>oRequest
<Object
></code>
974 <code>oRawResponse
<Object
></code>
975 The raw response from the live database
984 <dd>Parsed response object
</dd>
992 <a name=
"parseXMLData">parseXMLData
</a></h4>
999 <strong>parseXMLData
</strong>
1013 <div class=
"description">
1014 Overridable method parses raw XML data into a response object.
1017 <div class=
"description">
1020 <dt>Parameters:
</dt>
1022 <code>oRequest
<Object
></code>
1026 <code>oRawResponse
<Object
></code>
1027 The raw response from the live database
1036 <dd>Parsed response object
</dd>
1044 <a name=
"sendRequest">sendRequest
</a></h4>
1045 <div class=
"detail">
1051 <strong>sendRequest
</strong>
1069 <div class=
"description">
1070 First looks for cached response, then sends request to live data.
1073 <div class=
"description">
1076 <dt>Parameters:
</dt>
1078 <code>oRequest
<Object
></code>
1082 <code>oCallback
<Function
></code>
1083 Handler function to receive the response
1086 <code>oCaller
<Object
></code>
1087 The Calling object that is making the request
1104 <a name=
"toString">toString
</a></h4>
1105 <div class=
"detail">
1111 <strong>toString
</strong>
1116 <div class=
"description">
1117 Public accessor to the unique name of the DataSource instance.
1120 <div class=
"description">
1128 <dd>Unique name of the DataSource instance.
</dd>
1138 <div class=
"section field inheritance">
1139 <h4>Methods inherited from
<a href=
"YAHOO.util.EventProvider.html">YAHOO.util.EventProvider
</a>:
</h4>
1140 <div class=
"content">
1143 <a href=
"YAHOO.util.EventProvider.html#createEvent">createEvent
</a>,
1144 <a href=
"YAHOO.util.EventProvider.html#fireEvent">fireEvent
</a>,
1145 <a href=
"YAHOO.util.EventProvider.html#hasEvent">hasEvent
</a>,
1146 <a href=
"YAHOO.util.EventProvider.html#subscribe">subscribe
</a>,
1147 <a href=
"YAHOO.util.EventProvider.html#unsubscribe">unsubscribe
</a>,
1148 <a href=
"YAHOO.util.EventProvider.html#unsubscribeAll">unsubscribeAll
</a>
1153 <div class=
"section method details">
1154 <h3><a name=
"methodDetails">Events
</a></h3>
1155 <div class=
"content">
1157 <a name=
"cacheFlushEvent">cacheFlushEvent
</a></h4>
1158 <div class=
"detail">
1163 <strong>cacheFlushEvent
</strong>
1170 <div class=
"description">
1171 Fired when the local cache is flushed.
1174 <div class=
"description">
1184 <a name=
"cacheRequestEvent">cacheRequestEvent
</a></h4>
1185 <div class=
"detail">
1190 <strong>cacheRequestEvent
</strong>
1210 <div class=
"description">
1211 Fired when a request is made to the local cache.
1214 <div class=
"description">
1218 <dt>Parameters:
</dt>
1220 <code>oArgs.request
<Object
></code>
1224 <code>oArgs.callback
<Function
></code>
1225 The callback function.
1228 <code>oArgs.caller
<Object
></code>
1229 The parent object of the callback function.
1239 <a name=
"dataErrorEvent">dataErrorEvent
</a></h4>
1240 <div class=
"detail">
1245 <strong>dataErrorEvent
</strong>
1269 <div class=
"description">
1270 Fired when an error is encountered with the live data source.
1273 <div class=
"description">
1277 <dt>Parameters:
</dt>
1279 <code>oArgs.request
<Object
></code>
1283 <code>oArgs.callback
<Function
></code>
1284 The callback function.
1287 <code>oArgs.caller
<Object
></code>
1288 The parent object of the callback function.
1291 <code>oArgs.message
<String
></code>
1302 <a name=
"getCachedResponseEvent">getCachedResponseEvent
</a></h4>
1303 <div class=
"detail">
1308 <strong>getCachedResponseEvent
</strong>
1332 <div class=
"description">
1333 Fired when data is retrieved from the local cache.
1336 <div class=
"description">
1340 <dt>Parameters:
</dt>
1342 <code>oArgs.request
<Object
></code>
1346 <code>oArgs.response
<Object
></code>
1347 The response object.
1350 <code>oArgs.callback
<Function
></code>
1351 The callback function.
1354 <code>oArgs.caller
<Object
></code>
1355 The parent object of the callback function.
1365 <a name=
"parseResponseEvent">parseResponseEvent
</a></h4>
1366 <div class=
"detail">
1371 <strong>parseResponseEvent
</strong>
1395 <div class=
"description">
1396 Fired when live data source sends response.
1399 <div class=
"description">
1403 <dt>Parameters:
</dt>
1405 <code>oArgs.request
<Object
></code>
1409 <code>oArgs.response
<Object
></code>
1410 The raw response object.
1413 <code>oArgs.callback
<Function
></code>
1414 The callback function.
1417 <code>oArgs.caller
<Object
></code>
1418 The parent object of the callback function.
1428 <a name=
"requestEvent">requestEvent
</a></h4>
1429 <div class=
"detail">
1434 <strong>requestEvent
</strong>
1454 <div class=
"description">
1455 Fired when a request is sent to the live data source.
1458 <div class=
"description">
1462 <dt>Parameters:
</dt>
1464 <code>oArgs.request
<Object
></code>
1468 <code>oArgs.callback
<Function
></code>
1469 The callback function.
1472 <code>oArgs.caller
<Object
></code>
1473 The parent object of the callback function.
1483 <a name=
"responseCacheEvent">responseCacheEvent
</a></h4>
1484 <div class=
"detail">
1489 <strong>responseCacheEvent
</strong>
1513 <div class=
"description">
1514 Fired when response is cached.
1517 <div class=
"description">
1521 <dt>Parameters:
</dt>
1523 <code>oArgs.request
<Object
></code>
1527 <code>oArgs.response
<Object
></code>
1528 The parsed response object.
1531 <code>oArgs.callback
<Function
></code>
1532 The callback function.
1535 <code>oArgs.caller
<Object
></code>
1536 The parent object of the callback function.
1546 <a name=
"responseParseEvent">responseParseEvent
</a></h4>
1547 <div class=
"detail">
1552 <strong>responseParseEvent
</strong>
1576 <div class=
"description">
1577 Fired when response is parsed.
1580 <div class=
"description">
1584 <dt>Parameters:
</dt>
1586 <code>oArgs.request
<Object
></code>
1590 <code>oArgs.response
<Object
></code>
1591 The parsed response object.
1594 <code>oArgs.callback
<Function
></code>
1595 The callback function.
1598 <code>oArgs.caller
<Object
></code>
1599 The parent object of the callback function.
1620 <div class=
"module">
1622 <ul class=
"content">
1624 <li class=
""><a href=
"module_animation.html">animation
</a></li>
1626 <li class=
""><a href=
"module_autocomplete.html">autocomplete
</a></li>
1628 <li class=
""><a href=
"module_button.html">button
</a></li>
1630 <li class=
""><a href=
"module_calendar.html">calendar
</a></li>
1632 <li class=
""><a href=
"module_connection.html">connection
</a></li>
1634 <li class=
""><a href=
"module_container.html">container
</a></li>
1636 <li class=
"selected"><a href=
"module_datasource.html">datasource
</a></li>
1638 <li class=
""><a href=
"module_datatable.html">datatable
</a></li>
1640 <li class=
""><a href=
"module_dom.html">dom
</a></li>
1642 <li class=
""><a href=
"module_dragdrop.html">dragdrop
</a></li>
1644 <li class=
""><a href=
"module_element.html">element
</a></li>
1646 <li class=
""><a href=
"module_event.html">event
</a></li>
1648 <li class=
""><a href=
"module_history.html">history
</a></li>
1650 <li class=
""><a href=
"module_logger.html">logger
</a></li>
1652 <li class=
""><a href=
"module_menu.html">menu
</a></li>
1654 <li class=
""><a href=
"module_slider.html">slider
</a></li>
1656 <li class=
""><a href=
"module_tabview.html">tabview
</a></li>
1658 <li class=
""><a href=
"module_treeview.html">treeview
</a></li>
1660 <li class=
""><a href=
"module_yahoo.html">yahoo
</a></li>
1664 <div class=
"module">
1666 <ul class=
"content">
1667 <li class=
"selected"><a href=
"DataSource.html">DataSource
</a></li>
1671 <div class=
"module">
1673 <ul class=
"content">
1674 <li class=
""><a href=
"DataSource.js.html">DataSource.js
</a></li>
1678 <div class=
"module">
1680 <ul class=
"content">
1681 <li><a href=
"#_aCache">_aCache
</a>
1682 <!--<code><Number></code>-->
1684 <li><a href=
"#_nIndex">_nIndex
</a>
1685 <!--<code><Number></code>-->
1687 <li><a href=
"#_sName">_sName
</a>
1688 <!--<code><Number></code>-->
1690 <li><a href=
"#_xhrCallback">_xhrCallback
</a>
1691 <!--<code><Number></code>-->
1693 <li><a href=
"#connMgr">connMgr
</a>
1694 <!--<code><Number></code>-->
1696 <li><a href=
"#connTimeout">connTimeout
</a>
1697 <!--<code><Number></code>-->
1699 <li><a href=
"#dataType">dataType
</a>
1700 <!--<code><Number></code>-->
1702 <li><a href=
"#ERROR_DATAINVALID">ERROR_DATAINVALID
</a>
1703 <!--<code><Number></code>-->
1705 <li><a href=
"#ERROR_DATANULL">ERROR_DATANULL
</a>
1706 <!--<code><Number></code>-->
1708 <li><a href=
"#liveData">liveData
</a>
1709 <!--<code><Number></code>-->
1711 <li><a href=
"#maxCacheEntries">maxCacheEntries
</a>
1712 <!--<code><Number></code>-->
1714 <li><a href=
"#responseType">responseType
</a>
1715 <!--<code><Number></code>-->
1717 <li><a href=
"#TYPE_JSARRAY">TYPE_JSARRAY
</a>
1718 <!--<code><Number></code>-->
1720 <li><a href=
"#TYPE_JSFUNCTIOn">TYPE_JSFUNCTIOn
</a>
1721 <!--<code><Number></code>-->
1723 <li><a href=
"#TYPE_JSON">TYPE_JSON
</a>
1724 <!--<code><Number></code>-->
1726 <li><a href=
"#TYPE_TEXT">TYPE_TEXT
</a>
1727 <!--<code><Number></code>-->
1729 <li><a href=
"#TYPE_UNKNOWN">TYPE_UNKNOWN
</a>
1730 <!--<code><Number></code>-->
1732 <li><a href=
"#TYPE_XHR">TYPE_XHR
</a>
1733 <!--<code><Number></code>-->
1735 <li><a href=
"#TYPE_XML">TYPE_XML
</a>
1736 <!--<code><Number></code>-->
1741 <div class=
"module">
1743 <ul class=
"content">
1744 <li><!--<code>void</code>-->
1745 <a href=
"#_xhrFailure">_xhrFailure
</a>
1747 <li><!--<code>void</code>-->
1748 <a href=
"#_xhrSuccess">_xhrSuccess
</a>
1750 <li><!--<code>void</code>-->
1751 <a href=
"#addToCache">addToCache
</a>
1753 <li><!--<code>void</code>-->
1754 <a href=
"#flushCache">flushCache
</a>
1756 <li><!--<code>Object</code>-->
1757 <a href=
"#getCachedResponse">getCachedResponse
</a>
1759 <li><!--<code>void</code>-->
1760 <a href=
"#handleResponse">handleResponse
</a>
1762 <li><!--<code>Boolean</code>-->
1763 <a href=
"#isCacheHit">isCacheHit
</a>
1765 <li><!--<code>void</code>-->
1766 <a href=
"#makeConnection">makeConnection
</a>
1768 <li><!--<code>Object</code>-->
1769 <a href=
"#parseArrayData">parseArrayData
</a>
1771 <li><!--<code>Object</code>-->
1772 <a href=
"#parseJSONData">parseJSONData
</a>
1774 <li><!--<code>Object</code>-->
1775 <a href=
"#parseTextData">parseTextData
</a>
1777 <li><!--<code>Object</code>-->
1778 <a href=
"#parseXMLData">parseXMLData
</a>
1780 <li><!--<code>void</code>-->
1781 <a href=
"#sendRequest">sendRequest
</a>
1783 <li><!--<code>String</code>-->
1784 <a href=
"#toString">toString
</a>
1789 <div class=
"module">
1791 <ul class=
"content">
1793 <a href=
"#cacheFlushEvent">cacheFlushEvent
</a>
1796 <a href=
"#cacheRequestEvent">cacheRequestEvent
</a>
1799 <a href=
"#dataErrorEvent">dataErrorEvent
</a>
1802 <a href=
"#getCachedResponseEvent">getCachedResponseEvent
</a>
1805 <a href=
"#parseResponseEvent">parseResponseEvent
</a>
1808 <a href=
"#requestEvent">requestEvent
</a>
1811 <a href=
"#responseCacheEvent">responseCacheEvent
</a>
1814 <a href=
"#responseParseEvent">responseParseEvent
</a>
1825 Copyright
© 2007 Yahoo! Inc. All rights reserved.