[extjs.git] / extjs / packages / core / src / data / BufferedStore.js

/**\r
 * A BufferedStore maintains a sparsely populated map of pages corresponding to an extremely large server-side dataset.\r
 *\r
 * Use a BufferedStore when the dataset size is so large that the database and network latency, and client memory requirements\r
 * preclude caching the entire dataset in a regular {@link Ext.data.Store Store}.\r
 *\r
 * When using a BufferedStore *not all of the dataset is present in the client*. Only pages which have been\r
 * requested by the UI (usually a {@link Ext.grid.Panel GridPanel}) and surrounding pages will be present. Retention\r
 * of viewed pages in the BufferedStore after they have been scrolled out of view is configurable. See {@link #leadingBufferZone},\r
 * {@link #trailingBufferZone} and {@link #purgePageCount}.\r
 *\r
 * To use a BufferedStore, initiate the loading process by loading the first page. The number of rows rendered are\r
 * determined automatically, and the range of pages needed to keep the cache primed for scrolling is\r
 * requested and cached.\r
 * Example:\r
 *\r
 *     myBufferedStore.loadPage(1); // Load page 1\r
 *\r
 * A {@link Ext.grid.plugin.BufferedRenderer BufferedRenderer} is instantiated which will monitor the scrolling in the grid, and\r
 * refresh the view's rows from the page cache as needed. It will also pull new data into the page\r
 * cache when scrolling of the view draws upon data near either end of the prefetched data.\r
 *\r
 * The margins which trigger view refreshing from the prefetched data are {@link Ext.grid.plugin.BufferedRenderer#numFromEdge},\r
 * {@link Ext.grid.plugin.BufferedRenderer#leadingBufferZone} and {@link Ext.grid.plugin.BufferedRenderer#trailingBufferZone}.\r
 *\r
 * The margins which trigger loading more data into the page cache are, {@link #leadingBufferZone} and\r
 * {@link #trailingBufferZone}.\r
 *\r
 * By default, only 5 pages of data (in addition to the pages which over the visible region) are cached in the page cache,\r
 * with old pages being evicted from the cache as the view moves down through the dataset. This is controlled by the\r
 * {@link #purgePageCount} setting.\r
 *\r
 * Setting this value to zero means that no pages are *ever* scrolled out of the page cache, and\r
 * that eventually the whole dataset may become present in the page cache. This is sometimes desirable\r
 * as long as datasets do not reach astronomical proportions.\r
 *\r
 * Selection state may be maintained across page boundaries by configuring the SelectionModel not to discard\r
 * records from its collection when those Records cycle out of the Store's primary collection. This is done\r
 * by configuring the SelectionModel like this:\r
 *\r
 *     selModel: {\r
 *         pruneRemoved: false\r
 *     }\r
 *\r
 */\r
Ext.define('Ext.data.BufferedStore', {\r
    extend: 'Ext.data.ProxyStore',\r
\r
    alias: 'store.buffered',\r
\r
    requires: [\r
        'Ext.data.PageMap',\r
        'Ext.util.Filter',\r
        'Ext.util.Sorter',\r
        'Ext.util.Grouper'\r
    ],\r
    \r
    uses: [\r
        'Ext.util.SorterCollection',\r
        'Ext.util.FilterCollection',\r
        'Ext.util.GroupCollection'\r
    ],\r
\r
    /**\r
     * @property {Boolean} isBufferedStore\r
     * `true` in this class to identify an object as an instantiated BufferedStore, or subclass thereof.\r
     */\r
    isBufferedStore: true,\r
\r
    // For backward compatibility with user code.\r
    buffered: true,\r
\r
    config: {\r
        data: 0,\r
        pageSize: 25,\r
        remoteSort: true,\r
        remoteFilter: true,\r
        sortOnLoad: false,\r
        /**\r
        * @cfg {Number} purgePageCount\r
        *\r
        * The number of pages *in addition to twice the required buffered range* to keep in the prefetch cache before purging least recently used records.\r
        *\r
        * For example, if the height of the view area and the configured {@link #trailingBufferZone} and {@link #leadingBufferZone} require that there\r
        * are three pages in the cache, then a `purgePageCount` of 5 ensures that up to 11 pages can be in the page cache any any one time. This is enough\r
        * to allow the user to scroll rapidly between different areas of the dataset without evicting pages which are still needed.\r
        *\r
        * A value of 0 indicates to never purge the prefetched data.\r
        */\r
        purgePageCount: 5,\r
\r
        /**\r
        * @cfg {Number} trailingBufferZone\r
        * The number of extra records to keep cached on the trailing side of scrolling buffer\r
        * as scrolling proceeds. A larger number means fewer replenishments from the server.\r
        */\r
        trailingBufferZone: 25,\r
\r
        /**\r
        * @cfg {Number} leadingBufferZone\r
        * The number of extra rows to keep cached on the leading side of scrolling buffer\r
        * as scrolling proceeds. A larger number means fewer replenishments from the server.\r
        */\r
        leadingBufferZone: 200,\r
\r
        /**\r
         * @cfg {Number} defaultViewSize The default view size to use until the {@link #viewSize} has been configured.\r
         * @private\r
         */\r
        defaultViewSize: 100,    \r
\r
        /**\r
         * @cfg {Number} viewSize The view size needed to fill the current view. Defaults to the {@link #defaultViewSize}.\r
         * This will typically be set by the underlying view.\r
         * @private\r
         */\r
        viewSize: 0,\r
\r
        /**\r
         * @inheritdoc\r
         */\r
        trackRemoved: false\r
    },\r
\r
    /**\r
     * We are using applyData so that we can return nothing and prevent the `this.data`\r
     * property to be overridden.\r
     * @param {Array/Object} data\r
     */\r
    applyData: function(data) {\r
        var dataCollection = this.data || (this.data = this.createDataCollection());\r
\r
        //<debug>\r
        if (data && data !== true) {\r
            Ext.raise('Cannot load a buffered store with local data - the store is a map of remote data');\r
        }\r
        //</debug>\r
\r
        return dataCollection;\r
    },\r
\r
    applyProxy: function(proxy) {\r
        proxy = this.callParent([proxy]);\r
\r
        // This store asks for pages.\r
        // If used with a MemoryProxy, it must work\r
        if (proxy && proxy.setEnablePaging) {\r
            proxy.setEnablePaging(true);\r
        }\r
        return proxy;\r
    },\r
\r
    createFiltersCollection: function() {\r
        return new Ext.util.FilterCollection();\r
    },\r
\r
    createSortersCollection: function() {\r
        return new Ext.util.SorterCollection();\r
    },\r
\r
    //<debug>\r
    updateRemoteFilter: function(remoteFilter, oldRemoteFilter) {\r
        if (remoteFilter === false) {\r
            Ext.raise('Buffered stores are always remotely filtered.');\r
        }\r
        this.callParent([remoteFilter, oldRemoteFilter]);\r
    },\r
\r
    updateRemoteSort: function(remoteSort, oldRemoteSort) {\r
        if (remoteSort === false) {\r
            Ext.raise('Buffered stores are always remotely sorted.');\r
        }\r
        this.callParent([remoteSort, oldRemoteSort]);\r
    },\r
\r
    updateTrackRemoved: function(value) {\r
        if (value !== false) {\r
            Ext.raise('Cannot use trackRemoved with a buffered store.');\r
        }\r
        this.callParent(arguments);\r
    },\r
    //</debug>\r
\r
    updateGroupField: function(field) {\r
        this.group(field);\r
    },\r
\r
    getGrouper: function() {\r
        return this.grouper;\r
    },\r
\r
    isGrouped: function() {\r
        return !!this.grouper;\r
    },\r
\r
    createDataCollection: function() {\r
        var me = this,\r
            result = new Ext.data.PageMap({\r
                store: me,\r
                rootProperty: 'data',\r
                pageSize: me.getPageSize(),\r
                maxSize: me.getPurgePageCount(),\r
                listeners: {\r
                    // Whenever PageMap gets cleared, it means we re no longer interested in \r
                    // any outstanding page prefetches, so cancel tham all\r
                    clear: me.onPageMapClear,\r
                    scope: me\r
                }\r
            });\r
\r
        // Allow view to veto prune if the old page is still in use by the view\r
        me.relayEvents(result, ['beforepageremove', 'pageadd', 'pageremove']);\r
        me.pageRequests = {};\r
        return result;\r
    },\r
\r
    //<debug>\r
    add: function() {\r
        Ext.raise('add method may not be called on a buffered store - the store is a map of remote data');\r
    },\r
    \r
    insert: function() {\r
        Ext.raise('insert method may not be called on a buffered store - the store is a map of remote data');\r
    },\r
    //</debug>\r
\r
    removeAll: function(silent) {\r
        var me = this,\r
            data = me.getData();\r
\r
        if (data) {\r
            if (silent) {\r
                me.suspendEvent('clear');\r
            }\r
            data.clear();\r
            if (silent) {\r
                me.resumeEvent('clear');\r
            }\r
        }            \r
    },\r
\r
    flushLoad: function() {\r
        var me = this,\r
            options = me.pendingLoadOptions;\r
\r
        // If it gets called programatically, the listener will need cancelling\r
        me.clearLoadTask();\r
        if (!options) {\r
            return;\r
        }\r
\r
        // Buffered stores, a load operation means kick off a clean load from page 1\r
        me.getData().clear();\r
        options.page = 1;\r
        options.start = 0;\r
        options.limit = me.getViewSize() || me.getDefaultViewSize();\r
\r
        // If we're prefetching, the arguments on the callback for getting the range is different\r
        // So we indicate that we need to fire a special "load" style callback\r
        options.loadCallback = options.callback;\r
\r
        // options might be chained, with callback on a prototype; delete won't clear it.\r
        options.callback = null;\r
        return me.loadToPrefetch(options);\r
    },\r
\r
    reload: function(options) {\r
        var me = this,\r
            data = me.getData(),\r
            // If we don't have a known totalCount, use a huge value\r
            lastTotal = Number.MAX_VALUE,\r
            startIdx, endIdx, startPage, endPage,\r
            i, waitForReload, bufferZone, records;\r
\r
        if (!options) {\r
            options = {};\r
        }\r
\r
        // Prevent re-entering the load process if we are already in a wait state for a batch of pages.\r
        if (me.loading || me.fireEvent('beforeload', me, options) === false) {\r
            return;\r
        }\r
\r
        waitForReload = function() {\r
            var newCount = me.totalCount,\r
                oldRequestSize = endIdx - startIdx;\r
\r
            // If the dataset has now shrunk leaving the calculated request zone unavailable,\r
            // re-evaluate the request zone. Start as close to the end as possible.\r
            if (endIdx >= newCount) {\r
                endIdx = newCount - 1;\r
                startIdx = Math.max(endIdx - oldRequestSize, 0);\r
            }\r
            if (me.rangeCached(startIdx, Math.min(endIdx, me.totalCount))) {\r
                me.loading = false;\r
                data.un('pageadd', waitForReload);\r
                records = data.getRange(startIdx, endIdx + 1);\r
                me.fireEvent('load', me, records, true);\r
                me.fireEvent('refresh', me);\r
            }\r
        };\r
        bufferZone = Math.ceil((me.getLeadingBufferZone() + me.getTrailingBufferZone()) / 2);\r
\r
        // Decide what reload means.\r
        // If the View was configured preserveScrollOnReload, then it will\r
        // inject that setting here. This means that reload means\r
        // load the last requested range.\r
        if (me.lastRequestStart && me.preserveScrollOnReload) {\r
            startIdx = me.lastRequestStart;\r
            endIdx = me.lastRequestEnd;\r
            lastTotal = me.getTotalCount();\r
        }\r
        // Otherwise, reload means start from page 1\r
        else {\r
            startIdx = options.start || 0;\r
            endIdx = startIdx + (options.count || me.getPageSize()) - 1;\r
        }\r
\r
        // Clear page cache\r
        data.clear(true);\r
\r
        // So that prefetchPage does not consider the store to be fully loaded if the local count is equal to the total count\r
        delete me.totalCount;\r
\r
        // Calculate a page range which encompasses the Store's loaded range plus both buffer zones\r
        startIdx = Math.max(startIdx - bufferZone, 0);\r
        endIdx = Math.min(endIdx + bufferZone, lastTotal);\r
        startPage = me.getPageFromRecordIndex(startIdx);\r
        endPage = me.getPageFromRecordIndex(endIdx);\r
\r
        me.loading = true;\r
        options.waitForReload = waitForReload;\r
\r
        // Wait for the requested range to become available in the page map\r
        // Load the range as soon as the whole range is available\r
        data.on('pageadd', waitForReload);\r
\r
        // Recache the page range which encapsulates our visible records\r
        for (i = startPage; i <= endPage; i++) {\r
            me.prefetchPage(i, options);\r
        }\r
    },\r
\r
    filter: function() {\r
        //<debug>\r
        if (!this.getRemoteFilter()) {\r
            Ext.raise('Local filtering may not be used on a buffered store - the store is a map of remote data');\r
        }\r
        //</debug>\r
\r
        // Remote filtering forces a load. load clears the store's contents.\r
        this.callParent(arguments);\r
    },\r
\r
    filterBy: function(fn, scope) {\r
        //<debug>\r
        Ext.raise('Local filtering may not be used on a buffered store - the store is a map of remote data');\r
        //</debug>\r
    },\r
\r
    loadData: function(data, append) {\r
        //<debug>\r
        Ext.raise('LoadData may not be used on a buffered store - the store is a map of remote data');\r
        //</debug>\r
    },\r
\r
    loadPage: function(page, options) {\r
        var me = this;\r
        options = options || {};\r
\r
        options.page = me.currentPage = page;\r
        options.start = (page - 1) * me.getPageSize();\r
        options.limit = me.getViewSize() || me.getDefaultViewSize();\r
        options.loadCallback = options.callback;\r
\r
        // options might be chained, with callback on a prototype; delete won't clear it.\r
        options.callback = null;\r
        return me.loadToPrefetch(options);\r
    },\r
\r
    clearData: function(isLoad) {\r
        var me = this,\r
            data = me.getData();\r
\r
        if (data) {\r
            data.clear();\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * A BufferedStore always reports that it contains the full dataset.\r
     * The number of records that happen to be cached at any one time is never useful.\r
     */\r
    getCount: function() {\r
        return this.totalCount || 0;\r
    },\r
\r
    getRange: function(start, end, options) {\r
        var me = this,\r
            maxIndex = me.totalCount - 1,\r
            lastRequestStart = me.lastRequestStart,\r
            result = [],\r
            data = me.getData(),\r
            pageAddHandler,\r
            requiredStart, requiredEnd,\r
            requiredStartPage, requiredEndPage;\r
\r
        options = Ext.apply({\r
            prefetchStart: start,\r
            prefetchEnd: end\r
        }, options);\r
\r
        // Sanity check end point to be within dataset range\r
        end = (end >= me.totalCount) ? maxIndex : end;\r
\r
        // We must wait for a slightly wider range to be cached.\r
        // This is to allow grouping features to peek at the two surrounding records\r
        // when rendering a *range* of records to see whether the start of the range\r
        // really is a group start and the end of the range really is a group end.\r
        requiredStart = start === 0 ? 0 : start - 1;\r
        requiredEnd = end === maxIndex ? end : end + 1;\r
\r
        // Keep track of range we are being asked for so we can track direction of movement through the dataset\r
        me.lastRequestStart = start;\r
        me.lastRequestEnd = end;\r
\r
        // If data request can be satisfied from the page cache\r
        if (me.rangeCached(requiredStart, requiredEnd)) {\r
            me.onRangeAvailable(options);\r
            result = data.getRange(start, end + 1);\r
        }\r
        // At least some of the requested range needs loading from server\r
        else {\r
            // Private event used by the LoadMask class to perform masking when the range required for rendering is not found in the cache\r
            me.fireEvent('cachemiss', me, start, end);\r
\r
            requiredStartPage = me.getPageFromRecordIndex(requiredStart);\r
            requiredEndPage = me.getPageFromRecordIndex(requiredEnd);\r
\r
            // Add a pageadd listener, and as soon as the requested range is loaded, call onRangeAvailable to call the callback.\r
            pageAddHandler = function(pageMap, page, records) {\r
                if (page >= requiredStartPage && page <= requiredEndPage && me.rangeCached(requiredStart, requiredEnd)) {\r
                    // Private event used by the LoadMask class to unmask when the range required for rendering has been loaded into the cache\r
                    me.fireEvent('cachefilled', me, start, end);\r
                    data.un('pageadd', pageAddHandler);\r
                    me.onRangeAvailable(options);\r
                }\r
            };\r
            data.on('pageadd', pageAddHandler);\r
\r
            // Prioritize the request for the *exact range that the UI is asking for*.\r
            // When a page request is in flight, it will not be requested again by checking the me.pageRequests hash,\r
            // so the request after this will only request the *remaining* unrequested pages .\r
            me.prefetchRange(start, end);\r
\r
        }\r
        // Load the pages around the requested range required by the leadingBufferZone and trailingBufferZone.\r
        me.primeCache(start, end, start < lastRequestStart ? -1 : 1);\r
\r
        return result;\r
    },\r
    \r
    /**\r
     * Get the Record with the specified id.\r
     *\r
     * This method is not affected by filtering, lookup will be performed from all records\r
     * inside the store, filtered or not.\r
     *\r
     * @param {Mixed} id The id of the Record to find.\r
     * @return {Ext.data.Model} The Record with the passed id. Returns null if not found.\r
     */\r
    getById: function(id) {\r
        var result = this.data.findBy(function(record) {\r
            return record.getId() === id;\r
        });\r
        return result;\r
    },\r
\r
    /**\r
     * @inheritdoc\r
     */\r
    getAt: function(index) {\r
        var data = this.getData();\r
\r
        if (data.hasRange(index, index)) {\r
            return data.getAt(index);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * Get the Record with the specified internalId.\r
     *\r
     * This method is not effected by filtering, lookup will be performed from all records\r
     * inside the store, filtered or not.\r
     *\r
     * @param {Mixed} internalId The id of the Record to find.\r
     * @return {Ext.data.Model} The Record with the passed internalId. Returns null if not found.\r
     */\r
    getByInternalId: function(internalId) {\r
        return this.data.getByInternalId(internalId);\r
    },\r
\r
    // Inherit docs\r
    contains: function(record) {\r
        return this.indexOf(record) > -1;\r
    },\r
\r
    /**\r
     * Get the index of the record within the store.\r
     *\r
     * When store is filtered, records outside of filter will not be found.\r
     *\r
     * @param {Ext.data.Model} record The Ext.data.Model object to find.\r
     * @return {Number} The index of the passed Record. Returns -1 if not found.\r
     */\r
    indexOf: function(record) {\r
        return this.getData().indexOf(record);\r
    },\r
\r
    /**\r
     * Get the index within the store of the Record with the passed id.\r
     *\r
     * Like #indexOf, this method is effected by filtering.\r
     *\r
     * @param {String} id The id of the Record to find.\r
     * @return {Number} The index of the Record. Returns -1 if not found.\r
     */\r
    indexOfId: function(id) {\r
        return this.indexOf(this.getById(id));\r
    },\r
\r
    group: function(grouper, direction) {\r
        var me = this,\r
            oldGrouper;\r
        \r
        if (grouper && typeof grouper === 'string') {\r
            oldGrouper = me.grouper;\r
\r
                if (!oldGrouper) {\r
                    me.grouper = new Ext.util.Grouper({\r
                        property : grouper,\r
                        direction: direction || 'ASC',\r
                        root: 'data'\r
                    });\r
                } else if (direction === undefined) {\r
                    oldGrouper.toggle();\r
                } else {\r
                    oldGrouper.setDirection(direction);\r
                }\r
        } else {\r
            me.grouper = grouper ? me.getSorters().decodeSorter(grouper, 'Ext.util.Grouper') : null;\r
        }\r
\r
        me.getData().clear();\r
        me.loadPage(1, {\r
            callback: function() {\r
                me.fireEvent('groupchange', me, me.getGrouper());\r
            }\r
        });\r
    },\r
\r
    /**\r
     * Determines the page from a record index\r
     * @param {Number} index The record index\r
     * @return {Number} The page the record belongs to\r
     */\r
    getPageFromRecordIndex: function(index) {\r
        return Math.floor(index / this.getPageSize()) + 1;\r
    },\r
    \r
    calculatePageCacheSize: function(rangeSizeRequested) {\r
        var me = this,\r
            purgePageCount = me.getPurgePageCount();\r
\r
        // Calculate the number of pages that the cache will keep before purging  as follows:\r
        // TWO full rendering zones (in case of rapid teleporting by dragging the scroller) plus configured purgePageCount.\r
        // Ensure we never reduce the count. It always uses the largest requested block as the basis for the calculated size.\r
        return purgePageCount ? Math.max(me.getData().getMaxSize() || 0, Math.ceil((rangeSizeRequested + me.getTrailingBufferZone() + me.getLeadingBufferZone()) / me.getPageSize()) * 2 + purgePageCount) : 0;\r
    },\r
\r
    loadToPrefetch: function(options) {\r
        var me = this,\r
            prefetchOptions = options,\r
            i,\r
            records,\r
            dataSetSize,\r
\r
            // Get the requested record index range in the dataset\r
            startIdx = options.start,\r
            endIdx = options.start + options.limit - 1,\r
            rangeSizeRequested = (me.getViewSize() || options.limit),\r
\r
            // The end index to load into the store's live record collection\r
            loadEndIdx = Math.min(endIdx, options.start + rangeSizeRequested - 1),\r
\r
            // Calculate a page range which encompasses the requested range plus both buffer zones.\r
            // The endPage will be adjusted to be in the dataset size range as soon as the first data block returns.\r
            startPage = me.getPageFromRecordIndex(Math.max(startIdx - me.getTrailingBufferZone(), 0)),\r
            endPage = me.getPageFromRecordIndex(endIdx + me.getLeadingBufferZone()),\r
\r
            data = me.getData(),\r
            callbackFn = function () {\r
                // See comments in load() for why we need this.\r
                records = records || [];\r
\r
                if (options.loadCallback) {\r
                    options.loadCallback.call(options.scope || me, records, operation, true);\r
                }\r
\r
                if (options.callback) {\r
                    options.callback.call(options.scope || me, records, startIdx || 0, endIdx || 0, options);\r
                }\r
            },\r
            fireEventsFn = function () {\r
                me.fireEvent('datachanged', me);\r
                me.fireEvent('refresh', me);\r
                me.fireEvent('load', me, records, true);\r
            },\r
            // Wait for the viewable range to be available.\r
            waitForRequestedRange = function() {\r
                if (me.rangeCached(startIdx, loadEndIdx)) {\r
                    me.loading = false;\r
                    records = data.getRange(startIdx, loadEndIdx + 1);\r
                    data.un('pageadd', waitForRequestedRange);\r
\r
                    // If there is a listener for guaranteedrange then fire that event\r
                    if (me.hasListeners.guaranteedrange) {\r
                        me.guaranteeRange(startIdx, loadEndIdx, options.callback, options.scope);\r
                    }\r
\r
                    callbackFn();\r
                    fireEventsFn();\r
                }\r
            }, operation;\r
\r
        //<debug>\r
        if (isNaN(me.pageSize) || !me.pageSize) {\r
            Ext.raise('Buffered store configured without a pageSize', me);\r
        }\r
        //</debug>\r
\r
        // Ensure that the purgePageCount allows enough pages to be kept cached to cover the\r
        // requested range. If the pageSize is very small we might need a lot of pages.\r
        data.setMaxSize(me.calculatePageCacheSize(rangeSizeRequested));\r
\r
        if (me.fireEvent('beforeload', me, options) !== false) {\r
\r
            // So that prefetchPage does not consider the store to be fully loaded if the local count is equal to the total count\r
            delete me.totalCount;\r
\r
            me.loading = true;\r
\r
            // Any configured callback is handled in waitForRequestedRange above.\r
            // It should not be processed by onProxyPrefetch.\r
            if (options.callback) {\r
                prefetchOptions = Ext.apply({}, options);\r
                delete prefetchOptions.callback;\r
            }\r
\r
            // Load the first page in the range, which will give us the initial total count.\r
            // Once it is loaded, go ahead and prefetch any subsequent pages, if necessary.\r
            // The prefetchPage has a check to prevent us loading more than the totalCount,\r
            // so we don't want to blindly load up <n> pages where it isn't required.\r
            me.on('prefetch', function(store, records, successful, op) {\r
                // Capture operation here so it can be used in the loadCallback above\r
                operation = op;\r
                if (successful) {\r
                    // If there is data in the dataset, we can go ahead and add the pageadd listener which waits for the visible range\r
                    // and we can also issue the requests to fill the surrounding buffer zones.\r
                    if ((dataSetSize = me.getTotalCount())) {\r
\r
                        // Wait for the requested range to become available in the page map\r
                        data.on('pageadd', waitForRequestedRange);\r
\r
                        // As soon as we have the size of the dataset, ensure we are not waiting for more than can ever arrive,\r
                        loadEndIdx = Math.min(loadEndIdx, dataSetSize - 1);\r
\r
                        // And make sure we never ask for pages beyond the end of the dataset.\r
                        endPage = me.getPageFromRecordIndex(Math.min(loadEndIdx + me.getLeadingBufferZone(), dataSetSize - 1));\r
\r
                        for (i = startPage + 1; i <= endPage; ++i) {\r
                            me.prefetchPage(i, prefetchOptions);\r
                        }\r
                    } else {\r
                        callbackFn();\r
                        fireEventsFn();\r
                    }\r
                }\r
                // Unsuccessful prefetch: fire a load event with success false.\r
                else {\r
                    me.loading = false;\r
                    callbackFn();\r
                    me.fireEvent('load', me, records, false);\r
                }\r
            }, null, {single: true});\r
\r
            me.prefetchPage(startPage, prefetchOptions);\r
        }\r
    },\r
\r
    // Buffering\r
    /**\r
     * Prefetches data into the store using its configured {@link #proxy}.\r
     * @param {Object} options (Optional) config object, passed into the Ext.data.operation.Operation object before loading.\r
     * See {@link #method-load}\r
     */\r
    prefetch: function(options) {\r
        var me = this,\r
            pageSize = me.getPageSize(),\r
            data = me.getData(),\r
            operation,\r
            existingPageRequest;\r
\r
        // Check pageSize has not been tampered with. That would break page caching\r
        if (pageSize) {\r
            if (me.lastPageSize && pageSize != me.lastPageSize) {\r
                Ext.raise("pageSize cannot be dynamically altered");\r
            }\r
            if (!data.getPageSize()) {\r
                data.setPageSize(pageSize);\r
            }\r
        }\r
\r
        // Allow first prefetch call to imply the required page size.\r
        else {\r
            me.pageSize = data.setPageSize(pageSize = options.limit);\r
        }\r
\r
        // So that we can check for tampering next time through\r
        me.lastPageSize = pageSize;\r
\r
        // Always get whole pages.\r
        if (!options.page) {\r
            options.page = me.getPageFromRecordIndex(options.start);\r
            options.start = (options.page - 1) * pageSize;\r
            options.limit = Math.ceil(options.limit / pageSize) * pageSize;\r
        }\r
\r
        // Currently not requesting this page, or the request was for the last\r
        // generation of the data cache (clearing it changes generations)\r
        // then request it...\r
        existingPageRequest = me.pageRequests[options.page];\r
        if (!existingPageRequest || existingPageRequest.getOperation().pageMapGeneration !== data.pageMapGeneration) {\r
            // Copy options into a new object so as not to mutate passed in objects\r
            options = Ext.apply({\r
                action : 'read',\r
                filters: me.getFilters().items,\r
                sorters: me.getSorters().items,\r
                grouper: me.getGrouper(),\r
                internalCallback: me.onProxyPrefetch,\r
                internalScope: me\r
            }, options);\r
\r
            operation = me.createOperation('read', options);\r
\r
            // Generation # of the page map to which the requested records belong.\r
            // If page map is cleared while this request is in flight, the pageMapGeneration will increment and the payload will be rejected\r
            operation.pageMapGeneration = data.pageMapGeneration;\r
\r
            if (me.fireEvent('beforeprefetch', me, operation) !== false) {\r
                me.pageRequests[options.page] = operation.execute();\r
                if (me.getProxy().isSynchronous) {\r
                    delete me.pageRequests[options.page];\r
                }\r
            }\r
        }\r
\r
        return me;\r
    },\r
\r
    /**\r
     * @private\r
     * Cancels all pending prefetch requests.\r
     *\r
     * This is called when the page map is cleared.\r
     *\r
     * Any requests which still make it through will be for the previous pageMapGeneration\r
     * (pageMapGeneration is incremented upon clear), and so will be rejected upon arrival.\r
     */\r
    onPageMapClear: function() {\r
        var me = this,\r
            loadingFlag = me.wasLoading,\r
            reqs = me.pageRequests,\r
            data = me.getData(),\r
            page;\r
\r
        // If any requests return, we no longer respond to them.\r
        data.clearListeners();\r
\r
        // replace the listeners we need.\r
        data.on('clear', me.onPageMapClear, me);\r
        me.relayEvents(data, ['beforepageremove', 'pageadd', 'pageremove']);\r
\r
        // If the page cache gets cleared it's because a full reload is in progress.\r
        // Setting the loading flag prevents linked Views from displaying the empty text\r
        // during a load... we don't know whether ther dataset is empty or not.\r
        me.loading = true;\r
        me.totalCount = 0;\r
\r
        // Abort all outstanding requests.\r
        // onProxyPrefetch will reject them as being for the previous data generation\r
        // anyway, if they do return.\r
        // because of the pageMapGeneration mismatch.\r
        for (page in reqs) {\r
            if (reqs.hasOwnProperty(page)) {\r
                reqs[page].getOperation().abort();\r
            }\r
        }\r
\r
        // This will update any views. \r
        me.fireEvent('clear', me);\r
\r
        // Restore loading flag. The beforeload event could still veto the process.\r
        // The flag does not get set for real until we pass the beforeload event.\r
        me.loading = loadingFlag;\r
    },\r
\r
    /**\r
     * Prefetches a page of data.\r
     * @param {Number} page The page to prefetch\r
     * @param {Object} options (Optional) config object, passed into the Ext.data.operation.Operation object before loading.\r
     * See {@link #method-load}\r
     */\r
    prefetchPage: function(page, options) {\r
        var me = this,\r
            pageSize = me.getPageSize(),\r
            start = (page - 1) * pageSize,\r
            total = me.totalCount;\r
\r
        // No more data to prefetch.\r
        if (total !== undefined && me.data.getCount() === total) {\r
            return;\r
        }\r
\r
        // Copy options into a new object so as not to mutate passed in objects\r
        me.prefetch(Ext.applyIf({\r
            page     : page,\r
            start    : start,\r
            limit    : pageSize\r
        }, options));\r
    },\r
\r
    /**\r
     * Called after the configured proxy completes a prefetch operation.\r
     * @private\r
     * @param {Ext.data.operation.Operation} operation The operation that completed\r
     */\r
    onProxyPrefetch: function(operation) {\r
        if (this.destroyed) {\r
            return;\r
        }\r
        \r
        var me = this,\r
            resultSet = operation.getResultSet(),\r
            records = operation.getRecords(),\r
            successful = operation.wasSuccessful(),\r
            page = operation.getPage(),\r
            waitForReload = operation.waitForReload,\r
            oldTotal = me.totalCount,\r
            requests = me.pageRequests,\r
            key, op;\r
\r
        // Only cache the data if the operation was invoked for the current pageMapGeneration.\r
        // If the pageMapGeneration has changed since the request was fired off, it will have been cancelled.\r
        if (operation.pageMapGeneration === me.getData().pageMapGeneration) {\r
\r
            if (resultSet) {\r
                me.totalCount = resultSet.getTotal();\r
                if (me.totalCount !== oldTotal) {\r
                    me.fireEvent('totalcountchange', me.totalCount);\r
                }\r
            }\r
\r
            // Remove the loaded page from the outstanding pages hash\r
            if (page !== undefined) {\r
                delete me.pageRequests[page];\r
            }\r
\r
            // Prefetch is broadcast before the page is cached\r
            me.loading = false;\r
            me.fireEvent('prefetch', me, records, successful, operation);\r
\r
            // Add the page into the page map.\r
            // pageadd event may trigger the onRangeAvailable\r
            if (successful) {\r
                if (me.totalCount === 0) {\r
                    if (waitForReload) {\r
                        for (key in requests) {\r
                            op = requests[key].getOperation();\r
                            // Created in the same batch, clear the waitForReload so this\r
                            // won't be run again\r
                            if (op.waitForReload === waitForReload) {\r
                                delete op.waitForReload;\r
                            }\r
                        }\r
                        me.getData().un('pageadd', waitForReload);\r
                        me.fireEvent('load', me, [], true);\r
                        me.fireEvent('refresh', me);\r
                    }\r
                } else {\r
                    me.cachePage(records, operation.getPage());\r
                }\r
            }\r
\r
            //this is a callback that would have been passed to the 'read' function and is optional\r
            Ext.callback(operation.getCallback(), operation.getScope() || me, [records, operation, successful]);\r
        }\r
    },\r
\r
    /**\r
     * Caches the records in the prefetch and stripes them with their server-side\r
     * index.\r
     * @private\r
     * @param {Ext.data.Model[]} records The records to cache\r
     * @param {Ext.data.operation.Operation} page The associated operation\r
     */\r
    cachePage: function(records, page) {\r
        var me = this,\r
            len = records.length, i;\r
\r
        if (!Ext.isDefined(me.totalCount)) {\r
            me.totalCount = records.length;\r
            me.fireEvent('totalcountchange', me.totalCount);\r
        }\r
\r
        // Add the fetched page into the pageCache\r
        for (i = 0; i < len; i++) {\r
            records[i].join(me);\r
        }\r
        me.getData().addPage(page, records);\r
    },\r
\r
    /**\r
     * Determines if the passed range is available in the page cache.\r
     * @private\r
     * @param {Number} start The start index\r
     * @param {Number} end The end index in the range\r
     */\r
    rangeCached: function(start, end) {\r
        return this.getData().hasRange(start, end);\r
    },\r
\r
    /**\r
     * Determines if the passed page is available in the page cache.\r
     * @private\r
     * @param {Number} page The page to find in the page cache.\r
     */\r
    pageCached: function(page) {\r
        return this.getData().hasPage(page);\r
    },\r
\r
    /**\r
     * Determines if a request for a page is currently running\r
     * @private\r
     * @param {Number} page The page to check for\r
     */\r
    pagePending: function(page) {\r
        return !!this.pageRequests[page];\r
    },\r
\r
    /**\r
     * Determines if the passed range is available in the page cache.\r
     * @private\r
     * @deprecated 4.1.0 use {@link #rangeCached} instead\r
     * @param {Number} start The start index\r
     * @param {Number} end The end index in the range\r
     * @return {Boolean}\r
     */\r
    rangeSatisfied: function(start, end) {\r
        return this.rangeCached(start, end);\r
    },\r
\r
    /**\r
     * Handles the availability of a requested range that was not previously available\r
     * @private\r
     */\r
    onRangeAvailable: function(options) {\r
        var me = this,\r
            totalCount = me.getTotalCount(),\r
            start = options.prefetchStart,\r
            end = (options.prefetchEnd > totalCount - 1) ? totalCount - 1 : options.prefetchEnd,\r
            range;\r
\r
        end = Math.max(0, end);\r
\r
        //<debug>\r
        if (start > end) {\r
            Ext.log({\r
                level: 'warn',\r
                msg: 'Start (' + start + ') was greater than end (' + end +\r
                    ') for the range of records requested (' + start + '-' +\r
                    options.prefetchEnd + ')' + (this.storeId ? ' from store "' + this.storeId + '"' : '')\r
            });\r
        }\r
        //</debug>\r
\r
        range = me.getData().getRange(start, end + 1);\r
        if (options.fireEvent !== false) {\r
            me.fireEvent('guaranteedrange', range, start, end, options);\r
        }\r
        if (options.callback) {\r
            options.callback.call(options.scope || me, range, start, end, options);\r
        }\r
    },\r
\r
    /**\r
     * Guarantee a specific range, this will load the store with a range (that\r
     * must be the `pageSize` or smaller) and take care of any loading that may\r
     * be necessary.\r
     * @deprecated Use {@link #getRange}\r
     */\r
    guaranteeRange: function(start, end, callback, scope, options) {\r
         options = Ext.apply({\r
             callback: callback,\r
             scope: scope\r
         }, options);\r
         this.getRange(start, end + 1, options);\r
     },\r
\r
    /**\r
     * Ensures that the specified range of rows is present in the cache.\r
     *\r
     * Converts the row range to a page range and then only load pages which are not already\r
     * present in the page cache.\r
     */\r
    prefetchRange: function(start, end) {\r
        var me = this,\r
            startPage, endPage, page,\r
            data = me.getData();\r
\r
        if (!me.rangeCached(start, end)) {\r
            startPage = me.getPageFromRecordIndex(start);\r
            endPage = me.getPageFromRecordIndex(end);\r
\r
            // Ensure that the page cache's max size is correct.\r
            // Our purgePageCount is the number of additional pages *outside of the required range* which\r
            // may be kept in the cache. A purgePageCount of zero means unlimited.\r
            data.setMaxSize(me.calculatePageCacheSize(end - start + 1));\r
\r
            // We have the range, but ensure that we have a "buffer" of pages around it.\r
            for (page = startPage; page <= endPage; page++) {\r
                if (!me.pageCached(page)) {\r
                    me.prefetchPage(page);\r
                }\r
            }\r
        }\r
    },\r
\r
    primeCache: function(start, end, direction) {\r
        var me = this,\r
            leadingBufferZone = me.getLeadingBufferZone(),\r
            trailingBufferZone = me.getTrailingBufferZone(),\r
            pageSize = me.getPageSize(),\r
            totalCount = me.totalCount;\r
\r
        // Scrolling up\r
        if (direction === -1) {\r
            start = Math.max(start - leadingBufferZone, 0);\r
            end   = Math.min(end   + trailingBufferZone, totalCount - 1);\r
        }\r
        // Scrolling down\r
        else if (direction === 1) {\r
            start = Math.max(Math.min(start - trailingBufferZone, totalCount - pageSize), 0);\r
            end   = Math.min(end + leadingBufferZone, totalCount - 1);\r
        }\r
        // Teleporting\r
        else {\r
            start = Math.min(Math.max(Math.floor(start - ((leadingBufferZone + trailingBufferZone) / 2)), 0), totalCount - me.pageSize);\r
            end =   Math.min(Math.max(Math.ceil (end   + ((leadingBufferZone + trailingBufferZone) / 2)), 0), totalCount - 1);\r
        }\r
        me.prefetchRange(start, end);\r
    },\r
\r
    sort: function(field, direction, mode) {\r
        if (arguments.length === 0) {\r
            this.clearAndLoad();\r
        } else {\r
            this.getSorters().addSort(field, direction, mode);\r
        }\r
    },\r
\r
    onSorterEndUpdate: function() {\r
        var me = this,\r
            sorters = me.getSorters().getRange();\r
\r
        // Only load or sort if there are sorters\r
        if (sorters.length) {\r
            me.fireEvent('beforesort', me, sorters);\r
            me.clearAndLoad({\r
                callback: function() {\r
                    me.fireEvent('sort', me, sorters);\r
                }\r
            });\r
        } else {\r
            // Sort event must fire when sorters collection is updated to empty.\r
            me.fireEvent('sort', me, sorters);\r
        }\r
    },\r
\r
    clearAndLoad: function (options) {\r
        this.getData().clear();\r
        this.loadPage(1, options);\r
    },\r
\r
    privates: {\r
        isLast: function(record) {\r
            return this.indexOf(record) === this.getTotalCount() - 1;\r
        },\r
\r
        isMoving: function () {\r
            return false;\r
        }\r
    }\r
});\r