/**
 * Copyright (c) Richard Wall
 * See LICENSE for details.
 *
 * Wrappers and convenience fuctions for working with the javascriptRRD, jQuery,
 * and Flot charting packages.
 *
 * Designed to work well with the RRD files generated by Collectd:
 * - http://collectd.org/
 *
 * Requirements:
 * - javascriptRRD/rrdFile 0.6/1.1: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html
 * - javascriptRRD/binaryXHR 0.6/1.1: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html
 * - jQuery 1.6.3: http://jquery.com/
 * - Flot 1.7: http://www.flotcharts.org/
 * - jQueryTools/tabs: http://jquerytools.github.io/documentation/tabs/index.html
 * - jQueryTools/toolbox/history: http://jquerytools.github.io/documentation/toolbox/history.html
 */

/**
 * A namespace for Jarmon
 *
 * @namespace jarmon
 */
if(typeof(jarmon) === 'undefined') {
    var jarmon = {};
}

/**
 * An RrdDataSource is an object that provides a getData method that retrieves
 * the data for a single Data Source.
 *
 * @interface jarmon.RrdDataSource
 */

/**
 * @function
 * @name jarmon.RrdDataSource#getData
 * @param startTime {number} The start timestamp
 * @param endTime {number} The end timestamp
 * @return {module:jQuery.Deferred} A Deferred which calls back with a Flot data
 *      series.
 */

/**
 * @callback jarmon.RrdQueryRemote.Downloader
 * @param url {string} The url of the object to be downloaded
 * @return {module:jQuery.Deferred} A Deferred which will callback with an
 *      instance of {@link module:javascriptRRD/binaryXHR.BinaryFile}
 */

/**
 * Download a binary file asynchronously using the {@link jQuery.ajax}
 * function.
 *
 * @member
 * @type jarmon.RrdQueryRemote.Downloader
 *
 * @requires jQuery
 * @requires javascriptRRD/binaryXHR
 */
jarmon.downloadBinary = function(url) {
    var d = jQuery.Deferred();
    $.ajax({
        url: url,
        dataType: 'text',
        cache: false,
        mimeType: 'text/plain; charset=x-user-defined',
        xhr: function() {
            // Save a reference to the native xhr object - we need it later
            // in IE to access the binary data from responseBody
            this._nativeXhr = jQuery.ajaxSettings.xhr();
            return this._nativeXhr;
        },
        complete: function(jqXHR, textStatus) {
            this._nativeXhr = null;
            delete this._nativeXhr;
        },
        success: function(data, textStatus, jqXHR) {
            var response = this._nativeXhr.responseBody // for IE
            if (response==undefined) {
                response=this._nativeXhr.responseText // for standards-compliant browsers
            }
            d.resolve(new BinaryFile(response));
        },
        error: function(xhr, textStatus, errorThrown) {
            d.reject(new Error(textStatus + ':' + xhr.status));
        }
    });
    return d;
};


/**
 * Copied from jquery.flot.js and modified to allow timezone
 * adjustment.
 *
 * @method
 * @requires Flot
 *
 * @param v {number} The timestamp to be formatted
 * @param axis {Object} A hash containing information about the time axis
 * @return {string} The formatted datetime string
 **/
jarmon.localTimeFormatter = function (v, axis) {
    // map of app. size of time units in milliseconds
    var timeUnitSize = {
        "second": 1000,
        "minute": 60 * 1000,
        "hour": 60 * 60 * 1000,
        "day": 24 * 60 * 60 * 1000,
        "month": 30 * 24 * 60 * 60 * 1000,
        "year": 365.2425 * 24 * 60 * 60 * 1000
    };

    // Offset the input timestamp by the user defined amount
    var d = new Date(v + axis.options.tzoffset);

    // first check global format
    if (axis.options.timeformat !== null) {
        return $.plot.formatDate(
            d, axis.options.timeformat, axis.options.monthNames);
    }

    var t = axis.tickSize[0] * timeUnitSize[axis.tickSize[1]];
    var span = axis.max - axis.min;
    var suffix = (axis.options.twelveHourClock) ? " %p" : "";

    var fmt;
    if (t < timeUnitSize.minute)
        fmt = "%h:%M:%S" + suffix;
    else if (t < timeUnitSize.day) {
        if (span < 2 * timeUnitSize.day)
            fmt = "%h:%M" + suffix;
        else
            fmt = "%b %d %h:%M" + suffix;
    }
    else if (t < timeUnitSize.month)
        fmt = "%b %d";
    else if (t < timeUnitSize.year) {
        if (span < timeUnitSize.year)
            fmt = "%b";
        else
            fmt = "%b %y";
    }
    else
        fmt = "%y";

    return $.plot.formatDate(d, fmt, axis.options.monthNames);
};


/**
 * A wrapper around an instance of {@link module:javascriptRRD/rrdFile.RRDFile} which
 * provides a convenient way to query the RRDFile based on time range, RRD data
 * source (DS) and RRD consolidation function (CF).
 *
 * @constructor
 * @param rrd {module:javascriptRRD/rrdFile.RRDFile}
 * @param unit {string} The unit symbol for this data series
 **/
jarmon.RrdQuery = function(rrd, unit) {
    this.rrd = rrd;
    this.unit = unit;
};

/**
 * Generate a Flot compatible data object containing rows between start and end
 * time. The rows are taken from the first RRA whose data spans the requested
 * time range.
 *
 * @method
 * @param startTimeJs {number} start timestamp in microseconds
 * @param endTimeJs {number} end timestamp in microseconds
 * @param [dsId=0] {(string|number)} identifier of the RRD datasource
 * @param [cfName="AVERAGE"] {string} The name of an RRD consolidation function
 *      (CF) eg AVERAGE, MIN, MAX
 * @param {function} [transformer=function(v){return v}] A callable which
 *      performs a transformation of the values returned from the RRD file.
 * @return {module:Flot.data} A Flot-compatible data series
 *      eg `{label: '', data: [], unit: ''}`
 **/
jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs,
                                             dsId, cfName, transformer) {
    if (startTimeJs >= endTimeJs) {
        throw RangeError(
            ['starttime must be less than endtime.',
             'starttime:', startTimeJs,
             'endtime:', endTimeJs].join(' '));
    }

    var startTime = startTimeJs/1000;
    var lastUpdated = this.rrd.getLastUpdate();

    // default endTime to the last updated time (quantized to rrd step boundry)
    var endTime = lastUpdated - lastUpdated%this.rrd.getMinStep();
    if(endTimeJs) {
        endTime = endTimeJs/1000;
    }

    if(typeof(dsId) === 'undefined' && dsId !== null) {
        dsId = 0;
    }
    var ds = this.rrd.getDS(dsId);

    if(typeof(cfName) === 'undefined' && cfName !== null) {
        cfName = 'AVERAGE';
    }

    if(typeof(transformer) === 'undefined') {
        transformer = function(v) {return v;};
    }

    var rra, step, rraRowCount, lastRowTime, firstRowTime;

    for(var i=0; i<this.rrd.getNrRRAs(); i++) {
        // Look through all RRAs looking for the most suitable
        // data resolution.
        rra = this.rrd.getRRA(i);

        // If this rra doesn't use the requested CF then move on to the next.
        if(rra.getCFName() !== cfName) {
            continue;
        }

        step = rra.getStep();
        rraRowCount = rra.getNrRows();
        lastRowTime = lastUpdated-lastUpdated%step;
        firstRowTime = lastRowTime - rraRowCount * step;

        // We assume that the RRAs are listed in ascending order of time range,
        // therefore the first RRA which contains the range minimum should give
        // the highest resolution data for this range.
        if(firstRowTime <= startTime) {
            break;
        }
    }
    // If we got to the end of the loop without ever defining step, it means
    // that the CF check never succeded.
    if(!step) {
        throw TypeError('Unrecognised consolidation function: ' + cfName);
    }

    var flotData = [];
    var dsIndex = ds.getIdx();

    var startRowTime = Math.max(firstRowTime, startTime - startTime%step);
    var endRowTime = Math.min(lastRowTime, endTime - endTime%step);
    // If RRD exists, but hasn't been updated then the start time might end up
    // being higher than the end time (which is capped at the last row time of
    // the chosen RRA, so cap startTime at endTime...if you see what I mean)
    startRowTime = Math.min(startRowTime, endRowTime);

    /*
    console.log('FRT: ', new Date(firstRowTime*1000));
    console.log('LRT: ', new Date(lastRowTime*1000));
    console.log('SRT: ', new Date(startRowTime*1000));
    console.log('ERT: ', new Date(endRowTime*1000));
    console.log('DIFF: ', (lastRowTime - startRowTime) / step);
    console.log('ROWS: ', rraRowCount);
    */

    var startRowIndex = rraRowCount - (lastRowTime - startRowTime)  / step;
    var endRowIndex = rraRowCount - (lastRowTime - endRowTime)  / step;

    //console.log('SRI: ', startRowIndex);
    //console.log('ERI: ', endRowIndex);

    var val;
    var timestamp = startRowTime;
    for(i=startRowIndex; i<endRowIndex; i++) {
        val = transformer(rra.getEl(i, dsIndex));
        flotData.push([timestamp*1000.0, val]);
        timestamp += step;
    }

    // Now get the date of the earliest record in entire rrd file, ie that of
    // the last (longest range) rra.
    rra = this.rrd.getRRA(this.rrd.getNrRRAs()-1);
    var firstUpdated = lastUpdated - (rra.getNrRows() -1) * rra.getStep();

    return {'label': ds.getName(), 'data': flotData, 'unit': this.unit,
            'firstUpdated': firstUpdated*1000.0,
            'lastUpdated': lastUpdated*1000.0};
};


/**
 * Return a list of RRD Data Source names
 *
 * @method
 * @return {Array.<string>} An array of DS names.
 **/
jarmon.RrdQuery.prototype.getDSNames = function() {
    return this.rrd.getDSNames();
};


/**
 * A wrapper around {@link jarmon.RrdQuery} which provides asynchronous access
 * to the data in a remote RRD file.
 *
 * @constructor
 * @requires javascriptRRD/rrdFile
 * @implements {jarmon.RrdDataSource}
 *
 * @param url {string} The url of a remote RRD file
 * @param unit {string} The unit suffix of this data eg 'bit/sec'
 * @param [downloader=jarmon.downloadBinary] {jarmon.RrdQueryRemote.Downloader}
 **/
jarmon.RrdQueryRemote = function(url, unit, downloader) {
    this.url = url;
    this.unit = unit;
    if(typeof(downloader) == 'undefined') {
        this.downloader = jarmon.downloadBinary;
    } else {
        this.downloader = downloader;
    }

    this.lastUpdate = -Infinity;
    this._download = null;
};

/**
 * Asynchronously call a method on the underlying {@link jarmon.RrdQuery}.  Think of it
 * as an async .apply().
 *
 * @method
 * @private
 * @param methodName {string}
 * @param args {Array}
 * @return {module:jQuery.Deferred} A Deferred that calls .methodName(args...) on the
 *      underlying {@link jarmon.RrdQuery}.
 */
jarmon.RrdQueryRemote.prototype._callRemote = function(methodName, args) {
    // Download the rrd if there has never been a download and don't start
    // another download if one is already in progress.
    var self = this;
    if(!this._download) {
        this._download = this.downloader(this.url);
    }

    // Set up a deferred which will call getData on the local RrdQuery object
    // returning a Flot compatible data object to the caller.
    var ret = jQuery.Deferred();

    // Add a pair of callbacks to the current download which will callback the
    // result which we setup above.
    this._download.always(
        function(res) {
            if(res instanceof Error) {
                //ret.reject(res);
                result = {
                    data: [
                        [args[0], 0],
                        [args[1], 0]
                    ],
                    lines: {
                        lineWidth: 0
                    }
                };
                ret.resolve(result);
                return result;
            } else {
                // Upon successful download convert the resulting binary
                // into an RRD file
                var rrd = new RRDFile(res);
                self.lastUpdate = rrd.getLastUpdate();

                var rq = new jarmon.RrdQuery(rrd, self.unit);
                try {
                    ret.resolve(rq[methodName].apply(rq, args));
                } catch(e) {
                    ret.reject(e);
                }
            }
            return res;
        });

    return ret;
};


/**
 * Return a Flot compatible data series asynchronously.
 *
 * @method
 * @param startTime {number} The start timestamp
 * @param endTime {number} The end timestamp
 * @param [dsId=0] {(string|number)} identifier of the RRD datasource (string or number)
 * @param [cfName="AVERAGE"] {string} The name of an RRD consolidation function
 *      (CF) eg AVERAGE, MIN, MAX
 * @param {function} [transformer=function(v){return v}] A callable which
 *      performs a tranfsformation of the values returned from the RRD file.
 * @return {module:jQuery.Deferred} A Deferred which calls back with a Flot data
 *      series.
 **/
jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime,
                                                   dsId, cfName, transformer) {
    if(this.lastUpdate < endTime/1000) {
        this._download = null;
    }
    return this._callRemote('getData', [startTime, endTime, dsId, cfName, transformer]);
};


/**
 * Return a list of RRD Data Source names
 *
 * @method
 * @return {module:jQuery.Deferred} A Deferred which calls back with an array of
 *      DS names.
 **/
jarmon.RrdQueryRemote.prototype.getDSNames = function() {
    return this._callRemote('getDSNames');
};


/**
 * Wraps RrdQueryRemote to provide access to a different RRD DSs within a
 * single {@link jarmon.RrdQueryRemote}.
 *
 * @constructor
 * @implements {jarmon.RrdDataSource}
 *
 * @param rrdQuery {jarmon.RrdQueryRemote} An RrdQueryRemote instance
 * @param dsId {(string|number)} identifier of the RRD datasource (string or number)
 * @param {function} [transformer=function(v){return v}] A callable which
 *      performs a transformation of the values returned from the RRD file.
 **/
jarmon.RrdQueryDsProxy = function(rrdQuery, dsId, transformer) {
    this.rrdQuery = rrdQuery;
    this.dsId = dsId;
    this.unit = rrdQuery.unit;
    this.transformer = transformer;
};

/**
 * Call {@link jarmon.RrdQueryRemote#getData} with a particular dsId
 *
 * @method
 * @param startTime {number} A unix timestamp marking the start time
 * @param endTime {number} A unix timestamp marking the start time
 * @return {module:jQuery.Deferred} A Deferred which calls back with a Flot data
 *      series.
 **/
jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) {
    return this.rrdQuery.getData(startTime, endTime, this.dsId, undefined, this.transformer);
};


/**
 * A class for creating a Flot chart from a series of RRD Queries
 *
 * The `template` parameter should be a jQuery for a DOM node containing
 * elements matching these selectors:
 *
 * - `.title` : Placeholder for the title
 * - `.chart` : Placeholder for the chart itself
 * - `.graph-legend` : Placeholder for the chart legend
 * - `.error` : Placeholder for any error message (will be hidden on success)
 *
 * @constructor
 * @requires jQuery
 * @requires Flot
 *
 * @param template {module:jQuery.jQuery} A one-element jQuery containing
 *      placeholders for chart elements.
 * @param recipe {Object}
 * @param recipe.title {string}
 * @param recipe.data {Array}
 * @param recipe.options {module:Flot.options} Flot options which control how
 *      the chart should be drawn.
 **/
jarmon.Chart = function(template, recipe,  downloader) {
    this.template = template;
    this.recipe = recipe;
    this.downloader = downloader;

    this.options = jQuery.extend(true, {yaxis: {}}, recipe.options);

    this.data = [];

    this.setup();

    var self = this;


    // Listen for clicks on the legend items - onclick enable / disable the
    // corresponding data source.
    $('.graph-legend .legendItem', this.template[0]).live('click', function(e) {
        self.switchDataEnabled($(this).text());
        self.draw();
    });

    /* @todo The user should be able to override this with `ticks`, `tickSize`,
     *      or `minTickSize`.
     * @todo Look in to implementing this as a tickFormatter, and letting Flot
     *      take care of scaling.
     */
    this.options.yaxis.ticks = function(axis) {
        /*
         * Choose a suitable SI multiplier based on the min and max values from
         * the axis and then generate appropriate yaxis tick labels.
         *
         * @param axis {Object} An Object with min and max properties.
         * @return {Array.<string>} An array of ~5 tick labels.
         */
        var siPrefixes = {
            0: '',
            1: 'K',
            2: 'M',
            3: 'G',
            4: 'T'
        };
        var si = 0;
        while(true) {
            if( Math.pow(1000, si+1)*0.9 > (axis.max - axis.min) ) {
                break;
            }
            si++;
        }

        var minVal = axis.min/Math.pow(1000, si);
        var maxVal = axis.max/Math.pow(1000, si);

        var stepSizes = [0.01, 0.05, 0.1, 0.25, 0.5,
                         1, 2, 5, 10, 20, 25, 50, 100, 250];
        var realStep = (maxVal - minVal)/5.0;

        var stepSize, decimalPlaces = 0;
        for(var i=0; i<stepSizes.length; i++) {
            stepSize = stepSizes[i];
            if( realStep < stepSize ) {
                if(stepSize < 10) {
                    decimalPlaces = 2;
                }
                break;
            }
        }

        if(typeof(self.options.yaxis.tickDecimals) === 'number') {
            decimalPlaces = self.options.yaxis.tickDecimals;
        }

        var tickMin = minVal - minVal % stepSize;
        var tickMax = maxVal - maxVal % stepSize + stepSize;

        var ticks = [];
        for(var j=tickMin; j<=tickMax; j+=stepSize) {
            ticks.push([
                j*Math.pow(1000, si),
                j.toFixed(decimalPlaces)
            ]);
        }

        self.siPrefix = siPrefixes[si];

        return ticks;
    };
};

/**
 * @method
 */
jarmon.Chart.prototype.setup = function() {
    this.template.find('.title').text(this.recipe.title);
    this.data = [];
    var recipe = this.recipe;
    var dataDict = {};
    for(var j=0; j<recipe.data.length; j++) {
        var rrd = recipe.data[j][0];
        var ds = recipe.data[j][1];
        // Test for integer DS index as opposed to DS name
        var dsi = parseInt(ds, 10);
        if(ds.toString() === dsi.toString()) {
            ds = dsi;
        }
        var label = recipe.data[j][2];
        var unit = recipe.data[j][3];
        var transformer = recipe.data[j][4];

        if(typeof(dataDict[rrd]) === 'undefined') {
            dataDict[rrd] = new jarmon.RrdQueryRemote(
                rrd, unit, this.downloader);
        }
        this.addData(label, new jarmon.RrdQueryDsProxy(dataDict[rrd], ds, transformer));
    }
};

/**
 * Add details of a remote RRD data source whose data will be added to this
 * chart.
 *
 * @method
 * @param label {string} The label for this data which will be shown in the
 *      chart legend
 * @param db {string} The url of the remote RRD database
 * @param [enabled=true] {boolean} true if you want this data plotted on the chart,
 *      false if not.
 **/
jarmon.Chart.prototype.addData = function(label, db, enabled) {
    if(typeof(enabled) === 'undefined') {
        enabled = true;
    }
    this.data.push([label, db, enabled]);
};

/**
 * Enable / Disable a single data source
 *
 * @method
 * @param label {string} The label of the data source to be enabled /
 *      disabled.
 **/
jarmon.Chart.prototype.switchDataEnabled = function(label) {
    for(var i=0; i<this.data.length; i++) {
        if(this.data[i][0] === label) {
            this.data[i][2] = !this.data[i][2];
        }
    }
};

/**
 * Alter the time range of this chart and redraw
 *
 * @method
 * @param startTime {number} The start timestamp
 * @param endTime {number} The end timestamp
 * @return {Object} The same thing as .draw() returns
 **/
jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) {
    this.startTime = startTime;
    this.endTime = endTime;
    return this.draw();
};

/**
 * Draw the chart
 *
 * - A 'chart_loading' event is triggered before the data is requested
 * - A 'chart_loaded' event is triggered when the chart has been drawn
 *
 * @method
 * @return {module:jQuery.Deferred} A Deferred which calls back with the chart data
 *      when the chart has been rendered.
 **/
jarmon.Chart.prototype.draw = function() {
    var self = this;
    this.template.addClass('loading');

    var result;
    var results = [];
    for(var i=0; i<this.data.length; i++) {
        if(this.data[i][2]) {
            result = this.data[i][1].getData(this.startTime, this.endTime);
        } else {
            // If the data source has been marked as disabled return a fake
            // empty dataset
            // 0 values so that it can contribute to a stacked chart.
            // 0 linewidth so that it doesn't cause a line in stacked chart
            result = {
                data: [
                    [this.startTime, 0],
                    [this.endTime, 0]
                ],
                lines: {
                    lineWidth: 0
                }
            };
        }

        results.push(result);
    }

    return jQuery.when.apply(null, results).pipe(
        function() {
            var data = Array.prototype.slice.call(arguments);
            // Clear any previous error messages.
            self.template.find('.error').empty().hide();

            var i, label, disabled = [];
            var unit = '';
            for(i=0; i<data.length; i++) {
                label = self.data[i][0];
                if(label) {
                    data[i].label = label;
                }
                if(typeof(data[i].unit) !== 'undefined') {
                    // Just use the last unit for now
                    unit = data[i].unit;
                }
                if(!self.data[i][2]) {
                    disabled.push(label);
                }
            }

            $.plot(
                self.template.find('.chart').empty().show(),
                data, self.options);

            var yaxisUnitLabel = $('<div>')
                .text(self.siPrefix + unit)
                .addClass('yaxisUnitLabel');
            self.template.find('.chart').append(yaxisUnitLabel);

            // Manipulate and move the Flot generated legend to an
            // alternative position.
            // The default legend is formatted as an HTML table, so we
            // grab the contents of the cells and turn them into
            // divs.
            // Actually, formatting the legend first as a one column
            // table is useful as it generates an optimum label element
            // width which we can copy to the new divs + a little extra
            // to accomodate the color box
            //
            // @todo This seems super hacky
            // @todo Look in to implementing this using Flot
            //      `.legend.container`.
            var legend = self.template.find('.graph-legend').show();
            legend.empty();
            self.template.find('.legendLabel').each(
                function(i, el) {
                    var orig = $(el);
                    var label = orig.text();
                    var newEl = $('<div />', {
                        'class': 'legendItem',
                        'title': ('Data series switch - ' +
                                  'click to turn this data series on or off')
                    })
                        .width(orig.width()+20) // @todo Make this styleable
                        .text(label)
                        .prepend(
                            orig.prev()
                                .find('div div')
                                .clone().addClass('legendColorBox'))
                        .appendTo(legend);
                    // The legend label is clickable - to enable /
                    // disable different data series. The disabled class
                    // results in a label formatted with strike though
                    if( $.inArray(label, disabled) > -1 ) {
                        newEl.addClass('disabled');
                    }
                }
            ).remove();
            legend.append($('<div />').css('clear', 'both'));
            self.template.find('.legend').remove();

            yaxisUnitLabel.position(self.template.position());
            return data;
        }, null)
        .fail(
            function(failure) {
                self.template.find('.chart').empty().hide();
                self.template.find('.graph-legend').empty().hide();
                self.template.find('.error').text(
                    'error: ' + failure.message);

            })
        .always(
            function(res) {
                self.template.removeClass('loading');
                return res;
            });
};


/**
 * Generate a form through which to choose a data source from a remote RRD file
 *
 * @todo Create an example that uses this.
 *
 * @constructor
 * @requires jQuery
 *
 * @param $tpl {module:jQuery.jQuery} jQuery object for the DOM node to attach to.
 **/
jarmon.RrdChooser = function($tpl) {
    this.$tpl = $tpl;
    this.data = {
        rrdUrl: '',
        dsName: '',
        dsLabel: '',
        dsUnit:''
    };
};

/**
 * @method
 */
jarmon.RrdChooser.prototype.drawRrdUrlForm = function() {
    var self = this;
    this.$tpl.empty();

    $('<form/>').append(
        $('<div/>').append(
            $('<p/>').text('Enter the URL of an RRD file'),
            $('<label/>').append(
                'URL: ',
                $('<input/>', {
                    type: 'text',
                    name: 'rrd_url',
                    value: this.data.rrdUrl
                })
            ),
            $('<input/>', {'type': 'submit', value: 'download'}),
            $('<div/>', {'class': 'next'})
        )
    ).submit(
        function(e) {
            self.data.rrdUrl = this.rrd_url.value;
            var $placeholder = $(this).find('.next').empty();
            new jarmon.RrdQueryRemote(
                self.data.rrdUrl).getDSNames().addCallback(
                function($placeholder, dsNames) {
                    if(dsNames.length > 1) {
                        $('<p/>').text(
                            'The RRD file contains multiple data sources. ' +
                                'Choose one:').appendTo($placeholder);

                        $(dsNames).map(
                            function(i, el) {
                                return $('<input/>', {
                                    type: 'button',
                                    value: el
                                }
                            ).click(
                                function(e) {
                                    self.data.dsName = this.value;
                                    self.drawDsLabelForm();
                                }
                            );
                        }).appendTo($placeholder);
                    } else {
                        self.data.dsName = dsNames[0];
                        self.drawDsLabelForm();
                    }
                }, $placeholder
            ).addErrback(
                function($placeholder, err) {
                    $('<p/>', {'class': 'error'})
                        .text(err.toString()).appendTo($placeholder);
                }, $placeholder
            );
            return false;
        }
    ).appendTo(this.$tpl);
};

/**
 * @method
 */
jarmon.RrdChooser.prototype.drawDsLabelForm = function() {
    var self = this;
    this.$tpl.empty();

    $('<form/>').append(
        $('<p/>').text('Choose a label and unit for this data source.'),
        $('<div/>').append(
            $('<label/>').append(
                'Label: ',
                $('<input/>', {
                    type: 'text',
                    name: 'dsLabel',
                    value: this.data.dslabel || this.data.dsName
                })
            )
        ),
        $('<div/>').append(
            $('<label/>').append(
                'Unit: ',
                $('<input/>', {
                    type: 'text',
                    name: 'dsUnit',
                    value: this.data.dsUnit
                })
            )
        ),
        $('<input/>', {type: 'button', value: 'back'}).click(
            function(e) {
                self.drawRrdUrlForm();
            }
        ),
        $('<input/>', {type: 'submit', value: 'save'}),
        $('<div/>', {'class': 'next'})
    ).submit(
        function(e) {
            self.data.dsLabel = this.dsLabel.value;
            self.data.dsUnit = this.dsUnit.value;
            self.drawDsSummary();
            return false;
        }
    ).appendTo(this.$tpl);
};


/**
 * @method
 */
jarmon.RrdChooser.prototype.drawDsSummary = function() {
    var self = this;
    this.$tpl.empty();

    jQuery.each(this.data, function(i, el) {
        $('<p/>').append(
            $('<strong/>').text(i),
            [': ', el].join('')
        ).appendTo(self.$tpl);
    });

    this.$tpl.append(
        $('<input/>', {type: 'button', value: 'back'}).click(
            function(e) {
                self.drawDsLabelForm();
            }
        ),
        $('<input/>', {type: 'button', value: 'finish'})
    );
};


/**
 * UI element to toggle datasources in a graph.
 *
 * @constructor
 * @requires jQuery
 *
 * @param $tpl {module:jQuery.jQuery}
 * @param chart {jarmon.Chart}
 */
jarmon.ChartEditor = function($tpl, chart) {
    this.$tpl = $tpl;
    this.chart = chart;

    $('form', this.$tpl[0]).live(
        'submit',
        {self: this},
        function(e) {
            var self = e.data.self;
            self.chart.recipe.title = this.title.value;
            self.chart.recipe.data = $(this).find('.datasources tbody tr').map(
                function(i, el) {
                    return $(el).find('input[type=text]').map(
                        function(i, el) {
                            return el.value;
                        }
                    );
                }
            );
            self.chart.setup();
            self.chart.draw();
            return false;
        }
    );

    $('form', this.$tpl[0]).live(
        'reset',
        {self: this},
        function(e) {
            var self = e.data.self;
            self.draw();
            return false;
        }
    );

    $('form input[name=datasource_delete]', this.$tpl[0]).live(
        'click',
        function(e) {
            $(this).closest('tr').remove();
        }
    );

    $('form input[name=datasource_add]', this.$tpl[0]).live(
        'click',
        {self: this},
        function(e) {
            var self = e.data.self;
            self._addDatasourceRow(
                self._extractRowValues(
                    $(this).closest('tr')
                )
            );
            $(this).closest('tr').find('input[type=text]').val('');
        }
    );
};


/**
 * @method
 */
jarmon.ChartEditor.prototype.draw = function() {
    var self = this;
    this.$tpl.empty();

    $('<form/>').append(
        $('<div/>').append(
            $('<label/>').append(
                'Title: ',
                $('<input/>', {
                    type: 'text',
                    name: 'title',
                    value: this.chart.recipe.title
                })
            )
        ),
        $('<fieldset/>').append(
            $('<legend/>').text('Data Sources'),
            $('<table/>', {'class': 'datasources'}).append(
                $('<thead/>').append(
                    $('<tr/>').append(
                        $('<th/>').text('RRD File'),
                        $('<th/>').text('DS Name'),
                        $('<th/>').text('DS Label'),
                        $('<th/>').text('DS Unit'),
                        $('<th/>')
                    )
                ),
                $('<tfoot/>').append(
                    $('<tr/>').append(
                        $('<td/>').append(
                            $('<input/>', {type: 'text'})
                        ),
                        $('<td/>').append(
                            $('<input/>', {type: 'text'})
                        ),
                        $('<td/>').append(
                            $('<input/>', {type: 'text'})
                        ),
                        $('<td/>').append(
                            $('<input/>', {type: 'text'})
                        ),
                        $('<td/>').append(
                            $('<input/>', {
                                type: 'button',
                                value: 'add',
                                name: 'datasource_add'
                            })
                        )
                    )
                ),
                $('<tbody/>')
            )
        ),
        $('<input/>', {type: 'submit', value: 'save'}),
        $('<input/>', {type: 'reset', value: 'reset'})
    ).appendTo(this.$tpl);

    for(var i=0; i<this.chart.recipe.data.length; i++) {
        this._addDatasourceRow(this.chart.recipe.data[i]);
    }
};


/**
 * @method
 * @private
 * @param $row {module:jQuery.jQuery}
 * @return {module:jQuery.jQuery}
 */
jarmon.ChartEditor.prototype._extractRowValues = function($row) {
    return $row.find('input[type=text]').map(
        function(i, el) {
            return el.value;
        }
    );
};


/**
 * @method
 * @private
 * @param record {Array}
 */
jarmon.ChartEditor.prototype._addDatasourceRow = function(record) {
    $('<tr/>').append(
        $('<td/>').append(
            $('<input/>', {type: 'text', value: record[0]})
        ),
        $('<td/>').append(
            $('<input/>', {type: 'text', value: record[1]})
        ),
        $('<td/>').append(
            $('<input/>', {type: 'text', value: record[2]})
        ),
        $('<td/>').append(
            $('<input/>', {type: 'text', value: record[3]})
        ),
        $('<td/>').append(
            $('<input/>', {
                type: 'button',
                value: 'delete',
                name: 'datasource_delete'
            })
        )
    ).appendTo(this.$tpl.find('.datasources tbody'));
};


/**
 *
 * The `$tpl` is a jQuery around an the DOM node (probably an empty <div>) that
 * the tabbed interface will be placed inside of.
 *
 * The `recipe` is an array of `["Tab Name", [placeholder-name-list]]`
 * pairs.  For example:
 *
 *     recipe = [
 *         ["System",  ["cpu", "memory", "load"]],
 *         ["Network", ["interface"]]
 *     ];
 *
 * @constructor
 * @requires jQuery
 * @requires jQueryTools/tabs
 * @requires jQueryTools/toolbox/history
 *
 * @param $tpl {module:jQuery.jQuery}
 * @param recipe {Array.<Array.<string, Array.<string>>>} An array of
 *      `["Tab Name", [placeholder-name-list]]` pairs.
 */
jarmon.TabbedInterface = function($tpl, recipe) {
    this.$tpl = $tpl;
    this.recipe = recipe;
    /**
     * An array of `["placeholder-name", placeholder]` pairs.
     * @member
     * @type {Array.<Array.<string, module:jQuery.jQuery>>}
     */
    this.placeholders = [];

    this.$tabBar = $('<ul/>', {'class': 'css-tabs'}).appendTo($tpl);
    this.$tabPanels = $('<div/>', {'class': 'css-panes charts'}).appendTo($tpl);
    var tabName, $tabPanel, placeNames;
    for(var i=0; i<recipe.length; i++) {
        tabName = recipe[i][0];
        placeNames = recipe[i][1];

        $tabPanel = this.newTab(tabName);

        for(var j=0; j<placeNames.length; j++) {
            this.placeholders.push([
                placeNames[j], $('<div/>').appendTo($tabPanel)]);
        }
    }

    this.setup();
};

/**
 * @method
 * @param tabName {string}
 * @return {module:jQuery.jQuery} A <div> that is the contents of the tab panel.
 */
jarmon.TabbedInterface.prototype.newTab = function(tabName) {
    // Add a tab
    $('<li/>').append(
        $('<a/>', {href: ['#', tabName].join('')}).text(tabName)
    ).appendTo(this.$tabBar);
    var $placeholder = $('<div/>');
    // Add tab panel
    $('<div/>').append($placeholder).appendTo(this.$tabPanels);

    return $placeholder;
};

/**
 * @method
 */
jarmon.TabbedInterface.prototype.setup = function() {
    // Destroy then re-initialise the jquerytools tabs plugin
    var api = this.$tabBar.data("tabs");
    if(api) {
        api.destroy();
    }
    this.$tabBar.tabs(this.$tabPanels.children('div'), {history: true});
};

/**
 * Setup chart date range controls and all charts
 *
 * For each chart, a clone of the $chartTemplate are inserted into the document,
 * and these inserted copies are passed to `new {@link jarmon.Chart}()`.
 * Therefore, the $chartTemplate should have elements matching the same
 * selectors documented there.  However, in addition to those, it is useful to
 * have elements matching these selectors:
 *
 * - `input[name=chart_edit]` (optional) : A button to be clicked.  If present,
 *   when clicked, the graph-legend will turn in to a {@link
 *   jarmon.ChartEditor}, allowing the user to edit the chart's recipe.
 * - `input[name=chart_delete]` (optional) : A button to be clicked.  If
 *   present, when clicked, the graph will be removed from the UI.
 *
 * @todo Figure out how to allow `$chartTemplate` to be an HTML5 <template>
 *      element.
 *
 * @method
 * @requires jQuery
 *
 * @param $chartTemplate {module:jQuery.jQuery} See {@link jarmon.Chart}, see above
 * @param chartRecipes {Object.<string, recipe>} A map of
 *      placeholder-names (see {@link jarmon.TabbedInterface})
 *      to chart recipes (see {@link jarmon.Chart})
 * @param $tabTemplate {module:jQuery.jQuery} See {@link jarmon.TabbedInterface}
 * @param tabRecipes {Array} See {@link jarmon.TabbedInterface}
 * @param $controlPanelTemplate {module:jQuery.jQuery}
 * @return {Array.<Array.<jarmon.Chart>, jarmon.TabbedInterface, jarmon.ChartCoordinator>}
 **/
jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes,
                                      $tabTemplate, tabRecipes,
                                      $controlPanelTemplate) {
    var p = new jarmon.Parallimiter(2);
    function serialDownloader(url) {
        return p.addCallable(function(){ return jarmon.downloadBinary(url); });
    }

    var ti = new jarmon.TabbedInterface($tabTemplate, tabRecipes);

    var charts = jQuery.map(
        // As a reminder, TabbedInterface#placeholders is an array of
        // `["placeholder-name", jQuery-placeholder]` pairs.
        ti.placeholders,
        function(ph, i) {
            var chart = new jarmon.Chart(
                $chartTemplate.clone().appendTo(ph[1]),
                chartRecipes[ph[0]],
                serialDownloader
            );

            $('input[name=chart_edit]', ph[1][0]).live(
                'click',
                {chart: chart},
                function(e) {
                    var chart = e.data.chart;
                    var editor = new jarmon.ChartEditor(
                        chart.template.find('.graph-legend'),
                        chart);
                    editor.draw();
                }
            );

            $('input[name=chart_delete]', ph[1][0]).live(
                'click',
                {chart: chart},
                function(e) {
                    var chart = e.data.chart;
                    chart.template.remove();
                }
            );

            return chart;
        }
    );

    var cc = new jarmon.ChartCoordinator($controlPanelTemplate, charts);
    // Update charts when tab is clicked
    ti.$tpl.find(".css-tabs:first").bind('click',
        function(e) {
            // XXX: Hack to give the tab just enough time to become visible
            // so that Flot can calculate chart dimensions.
            window.clearTimeout(cc.t);
            cc.t = window.setTimeout(cc.update(), 100);
        }
    );

    // Initialise all the charts
    cc.update();

    return [charts, ti, cc];
};


/**
 * Options common to all the chart on this page
 *
 * This is not used by Jarmon internally; it is here for convenience to use as
 * part of chart recipes passed to {@linkcode jarmon.Chart new jarmon.Chart} (or
 * {@linkcode jarmon.buildTabbedChartUi}).
 *
 * @static
 * @default
 * @type module:Flot.options
 */
jarmon.Chart.BASE_OPTIONS = {
    grid: {
        clickable: false,
        borderWidth: 1,
        borderColor: "#000",
        color: "#000",
        backgroundColor: "#fff",
        tickColor: "#eee"
    },
    legend: {
        position: 'nw',
        noColumns: 1
    },
    selection: {
        mode: 'x'
    },
    series: {
        points: { show: false },
        lines: {
            show: true,
            steps: false,
            shadowSize: 0,
            lineWidth: 1
        },
        shadowSize: 0
    },
    xaxis: {
        mode: "time",
        tickFormatter: jarmon.localTimeFormatter
    }
};

/**
 * Extra options to generate a stacked chart
 *
 * This is not used by Jarmon internally; it is here for convenience to use as
 * part of chart recipes passed to {@linkcode jarmon.Chart new jarmon.Chart} (or
 * {@linkcode jarmon.buildTabbedChartUi}).
 *
 * @static
 * @default
 * @type module:Flot.options
 */
jarmon.Chart.STACKED_OPTIONS = {
    series: {
        stack: true,
        lines: {
            fill: 0.5
        }
    }
};


/**
 * A selection of useful time ranges
 *
 * For the most part, this is an array of `["human description", function]`
 * pairs.  However, if a third member of a tuple is `===true`, then that tuple
 * is used as the default option.  If no tuple is identified as the default this
 * way, then the default is the first tuple.
 *
 * @todo This should probably be a member of jarmon.ChartCoordinator.
 *
 * @member
 * @default
 */
jarmon.timeRangeShortcuts = [
    ['last hour', function(now) { return [now-60*60*1000*1, now]; }],
    ['last 3 hours', function(now) { return [now-60*60*1000*3, now]; }],
    ['last 6 hours', function(now) { return [now-60*60*1000*6, now]; }],
    ['last 12 hours', function(now) { return [now-60*60*1000*12, now]; }],
    ['last day', function(now) { return [now-60*60*1000*24, now]; }],
    ['last week', function(now) { return [now-60*60*1000*24*7, now]; }],
    ['last month', function(now) { return [now-60*60*1000*24*31, now]; }],
    ['last year', function(now) { return [now-60*60*1000*24*365, now]; }]
];


/**
 * Presents the user with a form and a timeline with which they can choose a
 * time range and co-ordinates the refreshing of a series of charts.
 *
 * The `ui` parameter should be a jQuery for a DOM node containing elements
 * matching these selectors:
 *
 * - `select[name="shortcuts"]` : An empty `<select>` to be populated with
 *   {@linkcode jarmon.timeRangeShortcuts}
 * - `[name="from"]` ; An input to select the start datetime
 * - `[name="to"]` : An input to select the end datetime
 * - `[name="tzoffset"]` : An input to select the timezone
 * - `[name="action"]` : A button to update the charts
 * - `.range-preview` : Placeholder for a Flot chart
 *
 * The `[name="to"]` and `[name="from"]` inputs should behave somewhat like
 * WHATWG HTML (revision 2016-12-12) `type=datetime-local` inputs with `step=1`.
 * Because `type=datetime-local` is not currently in a W3C spec, and not all
 * common browsers implement it, and polyfills vary in quality; Jarmon avoids
 * interacting with it too deeply, placing only a few requirements placed on the
 * implementation:
 *
 * - The value MUST be settable via `el.value = string` where `string` is of the
 *   format `%Y-%m-%dT%H:%M:%S`.
 * - The value MUST be gettable via `Date.parse(el.value+'Z')`.
 * - The user interface SHOULD prohibit the user from selecting a value that is
 *   before than the `min` attribute, which is in the format
 *   `%Y-%m-%dT%H:%M:%S`.
 * - The user interface SHOULD prohibit the user from selecting a value that is
 *   after than the `max` attribute, which is in the format `%Y-%m-%dT%H:%M:%S`.
 *
 * @constructor
 * @requires jQuery
 * @requires Flot
 *
 * @param ui {module:jQuery.jQuery} A one-element jQuery containing an input
 *      form and placeholders for the timeline and for the series of charts.
 * @param charts {Array.<jarmon.Chart>} An array of the charts that are to be
 *      coordinated.
 **/
jarmon.ChartCoordinator = function(ui, charts) {
    var self = this;
    this.ui = ui;
    this.charts = charts;

    // Style and configuration of the range timeline
    this.rangePreviewOptions = {
        grid: {
            borderWidth: 1
        },
        selection: {
            mode: 'x'
        },
        xaxis: {
            mode: 'time',
            tickFormatter: jarmon.localTimeFormatter
        },
        yaxis: {
            ticks: []
        }
    };

    this.inputs = {
        shortcuts: this.ui.find('select[name="shortcuts"]'),
        from:      this.ui.find('[name="from"]'),
        to:        this.ui.find('[name="to"]'),
        tzoffset:  this.ui.find('[name="tzoffset"]'),
        action:    this.ui.find('[name="action"]')
    };

    // DOM manipulation ////////////////////////////////////////////////////////

    // (This is put in a closure to avoid leaking variables and making it hard
    // for me to reason about the code.)
    (function(options, tzoffsetEl) {
        // Set up shortcuts
        var option;
        for(var i=0; i<jarmon.timeRangeShortcuts.length; i++) {
            option = $('<option />').text(jarmon.timeRangeShortcuts[i][0])
            if (jarmon.timeRangeShortcuts[i][2] === true) {
                option[0].setAttribute('selected', 'selected');
            }
            options.append(option);
        }
        // Append a custom option for when the user selects an area of the graph
        options.append($('<option />').text('custom'));

        // Populate a list of tzoffset options if the element is present in the
        // template as a select list
        if (tzoffsetEl.is('select')) {
            var label, val;
            for(i=-12; i<=12; i++) {
                label = 'UTC';
                val = i;
                if(val >= 0) {
                    label += ' + ';
                } else {
                    label += ' - ';
                }
                val = Math.abs(val).toString();
                if(val.length === 1) {
                    label += '0';
                }
                label += val + '00';
                tzoffsetEl.append(
                    $('<option />').attr('value', i*60*60*1000).text(label));
            }
        }

        // Default timezone offset based on localtime
        var tzoffset = -1 * (new Date()).getTimezoneOffset() * 60 * 1000;
        tzoffsetEl.val(tzoffset);
    })(this.inputs.shortcuts, this.inputs.tzoffset);

    // Event bindings //////////////////////////////////////////////////////////

    this.inputs.shortcuts.bind('change', function(e) {
        // No point in updating if the user chose custom.
        if($(this).val() !== 'custom') {
            self.update();
        }
    });

    this.inputs.from.bind('change',
        function(e) {
            self.inputs.shortcuts.val('custom');
            self.update();
        }
    );

    this.inputs.to.bind('change',
        function(e) {
            self.inputs.shortcuts.val('custom');
            self.update();
        }
    );

    this.inputs.tzoffset.bind('change', function(e) {
        self.update();
    });

    this.inputs.action.bind('click', function(e) {
        self.update();
        return false;
    });

    // When a selection is made on the range timeline, or any of my charts
    // redraw all the charts.
    $(document).bind('plotselected', {},
        function(e, ranges) {
            var eventSourceIsMine = false;

            // plotselected event may be from my range selector chart or
            if (self.ui.has(e.target) ) {
                eventSourceIsMine = true;
            } else {
                // ...it may come from one of the charts under my supervision
                for(var i=0; i<self.charts.length; i++) {
                    if(self.charts[i].template.has(e.target).length > 0) {
                        eventSourceIsMine = true;
                        break;
                    }
                }
            }

            if(eventSourceIsMine) {
                self.setTimeRange(ranges.xaxis.from, ranges.xaxis.to);
            }
        }
    );
};

/**
 * Grab the start and end time from the ui form, highlight the range on the
 * range timeline and set the time range of all the charts and redraw.
 *
 * @method
 * @return {module:jQuery.Deferred}
 **/
jarmon.ChartCoordinator.prototype.update = function() {
    var self = this;
    var shortcut = this.inputs.shortcuts.val();

    var now = new Date();
    for(var i=0; i<jarmon.timeRangeShortcuts.length; i++) {
        if(jarmon.timeRangeShortcuts[i][0] === shortcut) {
            var range = jarmon.timeRangeShortcuts[i][1](now.getTime());
            this.inputs.from.val(this.unix2datetimelocal(range[0]))
            this.inputs.to.val(this.unix2datetimelocal(range[1]));
            break;
        }
    }

    var startTime = this.datetimelocal2unix(this.inputs.from.val());
    var endTime = this.datetimelocal2unix(this.inputs.to.val());
    var tzoffset = parseInt(this.inputs.tzoffset.val(), 10);

    this.inputs.from[0].setAttribute('max', this.inputs.to.val());
    this.inputs.to[0].setAttribute(  'min', this.inputs.from.val());
    this.inputs.to[0].setAttribute(  'max', now.toISOString().slice(0, -1));

    this.rangePreviewOptions.xaxis.tzoffset = tzoffset;

    var chartsLoading = [];
    for(i=0; i<this.charts.length; i++){
        this.charts[i].options.xaxis.tzoffset = tzoffset;
        // Don't render charts which are not currently visible
        if(this.charts[i].template.is(':visible')) {
            chartsLoading.push(
                this.charts[i].setTimeRange(startTime, endTime));
        }
    }
    return jQuery.when.apply(null, chartsLoading).done(
        function() {
            var chartData = Array.prototype.slice.call(arguments);

            var firstUpdate = new Date().getTime();
            var lastUpdate = 0;

            for(var i=0; i<chartData.length; i++) {
                for(var j=0; j<chartData[i].length; j++) {
                    if(chartData[i][j].firstUpdated < firstUpdate) {
                        firstUpdate = chartData[i][j].firstUpdated;
                    }
                    if(chartData[i][j].lastUpdated > lastUpdate) {
                        lastUpdate = chartData[i][j].lastUpdated;
                    }
                }
            }

            var ranges = {
                xaxis: {
                    from: Math.max(startTime, firstUpdate),
                    to: Math.min(endTime, lastUpdate)
                }
            };

            // Add a suitable extended head and tail to preview graph time axis
            var HOUR = 1000 * 60 * 60;
            var DAY = HOUR * 24;
            var WEEK = DAY * 7;
            var MONTH = DAY * 31;
            var YEAR = DAY * 365;
            var periods = [HOUR, HOUR*6, HOUR*12,
                           DAY, DAY*3,
                           WEEK, WEEK*2,
                           MONTH, MONTH*3, MONTH*6, YEAR];

            var range = ranges.xaxis.to - ranges.xaxis.from;
            for(i=0; i<periods.length; i++) {
                if(range <= periods[i]) {
                    i++;
                    break;
                }
            }

            // Dummy data for the range timeline
            var data = [
                [Math.max(ranges.xaxis.from - periods[i-1], firstUpdate), 1],
                [Math.min(ranges.xaxis.to + periods[i-1], lastUpdate), 1]];

            self.rangePreview = $.plot(self.ui.find('.range-preview'), [data],
                                       self.rangePreviewOptions);

            self.rangePreview.setSelection(ranges, true);
        });
};

/**
 * Convert a UNIX millisecond timestamp into a [datetime-local string][]; using
 * the `[name="tzoffoffset"]` input for the timezone.
 *
 * [datetime-local string]: https://html.spec.whatwg.org/multipage/infrastructure.html#concept-datetime-local
 *
 * @method
 * @private
 * @param unix {number}
 * @return {string}
 */
jarmon.ChartCoordinator.prototype.unix2datetimelocal = function(unix) {
    var tz = parseInt(this.inputs.tzoffset.val(), 10);
    return (new Date(unix + tz)).toISOString().slice(0, -1);
}

/**
 * Convert a [datetime-local string][] into a UNIX millisecond timestamp; using
 * the `[name="tzoffoffset"]` input for the timezone.
 *
 * [datetime-local string]: https://html.spec.whatwg.org/multipage/infrastructure.html#concept-datetime-local
 *
 * @method
 * @private
 * @param datetimelocal {string}
 * @return {number}
 */
jarmon.ChartCoordinator.prototype.datetimelocal2unix = function(datetimelocal) {
    var tz = parseInt(this.inputs.tzoffset.val(), 10);
    return Date.parse(datetimelocal+'Z') - tz;
};

/**
 * Set the start and end time fields in the form and trigger an update
 *
 * @method
 * @param [startTime=] {number} The start timestamp
 * @param [endTime=] {number} The end timestamp
 **/
jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
    if(typeof(from) !== 'undefined' && from !== null) {
        this.inputs.from.val(this.unix2datetimelocal(from))
    }
    if(typeof(to) !== 'undefined' && to !== null) {
        this.inputs.to.val(this.unix2datetimelocal(to));
    }
    this.inputs.shortcuts.val('custom');
    this.update();
};

/**
 * An alias for {@linkcode jarmon.ChartCoordinator#update .update()}.
 *
 * @method
 * @deprecated Use {@linkcode jarmon.ChartCoordinator#update .update()} instead.
 **/
jarmon.ChartCoordinator.prototype.init = function() {
    this.update();
};

/**
 * Limit the number of parallel async calls
 *
 * @constructor
 * @requires jQuery
 *
 * @param limit {number} The maximum number of in progress calls
 **/
jarmon.Parallimiter = function(limit) {
    this.limit = limit || 1;
    this._callQueue = [];
    this._currentCallCount = 0;
};

/**
 * Add a function to be called when the number of in progress calls drops
 * below the configured limit
 *
 * @todo Remove the `args` argument in favor of passing in closures.
 *
 * @method
 * @param callable {function} A function which returns a Deferred.
 * @param args {Array} A list of arguments to pass to the callable
 * @return {module:jQuery.jQuery} A Deferred which fires with the result of the callable
 *       when it is called.
 **/
jarmon.Parallimiter.prototype.addCallable = function(callable, args) {
    var d = new jQuery.Deferred();
    this._callQueue.unshift([d, callable, args]);
    this._nextCall();
    return d;
};

/**
 * @method
 * @private
 */
jarmon.Parallimiter.prototype._nextCall = function() {
    var self = this;
    if(this._callQueue.length > 0) {
        if(this._currentCallCount < this.limit) {
            this._currentCallCount++;
            var nextCall = this._callQueue.pop();
            nextCall[1].apply(null, nextCall[2]).always(
                function(res) {
                    nextCall[0].resolve(res);
                    self._currentCallCount--;
                    self._nextCall();
                });
        }
    }
};