/javascripts/lib/src/direct/PollingProvider.js

  1/*!
  2 * Ext JS Library 3.2.1
  3 * Copyright(c) 2006-2010 Ext JS, Inc.
  4 * licensing@extjs.com
  5 * http://www.extjs.com/license
  6 */
  7/**
  8 * @class Ext.direct.PollingProvider
  9 * @extends Ext.direct.JsonProvider
 10 *
 11 * <p>Provides for repetitive polling of the server at distinct {@link #interval intervals}.
 12 * The initial request for data originates from the client, and then is responded to by the
 13 * server.</p>
 14 * 
 15 * <p>All configurations for the PollingProvider should be generated by the server-side
 16 * API portion of the Ext.Direct stack.</p>
 17 *
 18 * <p>An instance of PollingProvider may be created directly via the new keyword or by simply
 19 * specifying <tt>type = 'polling'</tt>.  For example:</p>
 20 * <pre><code>
 21var pollA = new Ext.direct.PollingProvider({
 22    type:'polling',
 23    url: 'php/pollA.php',
 24});
 25Ext.Direct.addProvider(pollA);
 26pollA.disconnect();
 27
 28Ext.Direct.addProvider(
 29    {
 30        type:'polling',
 31        url: 'php/pollB.php',
 32        id: 'pollB-provider'
 33    }
 34);
 35var pollB = Ext.Direct.getProvider('pollB-provider');
 36 * </code></pre>
 37 */
 38Ext.direct.PollingProvider = Ext.extend(Ext.direct.JsonProvider, {
 39    /**
 40     * @cfg {Number} priority
 41     * Priority of the request (defaults to <tt>3</tt>). See {@link Ext.direct.Provider#priority}.
 42     */
 43    // override default priority
 44    priority: 3,
 45    
 46    /**
 47     * @cfg {Number} interval
 48     * How often to poll the server-side in milliseconds (defaults to <tt>3000</tt> - every
 49     * 3 seconds).
 50     */
 51    interval: 3000,
 52
 53    /**
 54     * @cfg {Object} baseParams An object containing properties which are to be sent as parameters
 55     * on every polling request
 56     */
 57    
 58    /**
 59     * @cfg {String/Function} url
 60     * The url which the PollingProvider should contact with each request. This can also be
 61     * an imported Ext.Direct method which will accept the baseParams as its only argument.
 62     */
 63
 64    // private
 65    constructor : function(config){
 66        Ext.direct.PollingProvider.superclass.constructor.call(this, config);
 67        this.addEvents(
 68            /**
 69             * @event beforepoll
 70             * Fired immediately before a poll takes place, an event handler can return false
 71             * in order to cancel the poll.
 72             * @param {Ext.direct.PollingProvider}
 73             */
 74            'beforepoll',            
 75            /**
 76             * @event poll
 77             * This event has not yet been implemented.
 78             * @param {Ext.direct.PollingProvider}
 79             */
 80            'poll'
 81        );
 82    },
 83
 84    // inherited
 85    isConnected: function(){
 86        return !!this.pollTask;
 87    },
 88
 89    /**
 90     * Connect to the server-side and begin the polling process. To handle each
 91     * response subscribe to the data event.
 92     */
 93    connect: function(){
 94        if(this.url && !this.pollTask){
 95            this.pollTask = Ext.TaskMgr.start({
 96                run: function(){
 97                    if(this.fireEvent('beforepoll', this) !== false){
 98                        if(typeof this.url == 'function'){
 99                            this.url(this.baseParams);
100                        }else{
101                            Ext.Ajax.request({
102                                url: this.url,
103                                callback: this.onData,
104                                scope: this,
105                                params: this.baseParams
106                            });
107                        }
108                    }
109                },
110                interval: this.interval,
111                scope: this
112            });
113            this.fireEvent('connect', this);
114        }else if(!this.url){
115            throw 'Error initializing PollingProvider, no url configured.';
116        }
117    },
118
119    /**
120     * Disconnect from the server-side and stop the polling process. The disconnect
121     * event will be fired on a successful disconnect.
122     */
123    disconnect: function(){
124        if(this.pollTask){
125            Ext.TaskMgr.stop(this.pollTask);
126            delete this.pollTask;
127            this.fireEvent('disconnect', this);
128        }
129    },
130
131    // private
132    onData: function(opt, success, xhr){
133        if(success){
134            var events = this.getEvents(xhr);
135            for(var i = 0, len = events.length; i < len; i++){
136                var e = events[i];
137                this.fireEvent('data', this, e);
138            }
139        }else{
140            var e = new Ext.Direct.ExceptionEvent({
141                data: e,
142                code: Ext.Direct.exceptions.TRANSPORT,
143                message: 'Unable to connect to the server.',
144                xhr: xhr
145            });
146            this.fireEvent('data', this, e);
147        }
148    }
149});
150
151Ext.Direct.PROVIDERS['polling'] = Ext.direct.PollingProvider;