terriajs/lib/Models/Catalog.js

Geospatial data visualization platform.

'use strict';

/*global require*/

var defined = require('terriajs-cesium/Source/Core/defined');
var defaultValue = require('terriajs-cesium/Source/Core/defaultValue');
var defineProperties = require('terriajs-cesium/Source/Core/defineProperties');
var DeveloperError = require('terriajs-cesium/Source/Core/DeveloperError');
var knockout = require('terriajs-cesium/Source/ThirdParty/knockout');
var CatalogGroup = require('./CatalogGroup');
var when = require('terriajs-cesium/Source/ThirdParty/when');

/**
 * The view model for the data catalog.
 *
 * @param {Terria} terria The Terria instance.
 *
 * @alias Catalog
 * @constructor
 */
var Catalog = function(terria) {
    if (!defined(terria)) {
        throw new DeveloperError('terria is required');
    }

    this._terria = terria;
    this._shareKeyIndex = {};

    this._group = new CatalogGroup(terria);
    this._group.name = 'Root Group';
    this._group.preserveOrder = true;

    /**
     * Gets or sets a flag indicating whether the catalog is currently loading.
     * @type {Boolean}
     */
    this.isLoading = false;

    /**
     * Gets or sets an array of non-geospatial, chartable catalog items.
     * @type {CsvCatalogItem[]}
     */
    this.chartableItems = [];

    knockout.track(this, ['isLoading', 'chartableItems']);

    knockout.defineProperty(this, 'userAddedDataGroup', {
        get: this.upsertCatalogGroup.bind(this, CatalogGroup, 'User-Added Data', 'The group for data that was added by the user via the Add Data panel.')
    });
};

defineProperties(Catalog.prototype, {
    /**
      * Gets the Terria instance.
     * @memberOf Catalog.prototype
     * @type {Terria}
     */
    terria : {
        get : function() {
            return this._terria;
        }
    },

    /**
     * Gets the catalog's top-level group.
     * @memberOf Catalog.prototype
     * @type {CatalogGroup}
     */
    group : {
        get : function() {
            return this._group;
        }
    },

    /**
     * A flat index of all catalog member in this catalog by their share keys. Because items can have multiple share keys
     * to preserve backwards compatibility, multiple entries in this index will lead to the same catalog member.
     *
     * @type {Object}
     */
    shareKeyIndex : {
        get : function() {
            return this._shareKeyIndex;
        }
    }
});

/**
 * Updates the catalog from a JSON object-literal description of the available collections.
 * Existing collections with the same name as a collection in the JSON description are
 * updated.  If the description contains a collection with a name that does not yet exist,
 * it is created.  Because parts of the update may happen asynchronously, this method
 * returns at Promise that will resolve when the update is completely done.
 *
 * @param {Object} json The JSON description.  The JSON should be in the form of an object literal, not a string.
 * @param {Object} [options] Object with the following properties:
 * @param {Boolean} [options.onlyUpdateExistingItems] true to only update existing items and never create new ones, or false is new items
 *                                                    may be created by this update.
 * @param {Boolean} [options.isUserSupplied] If specified, sets the {@link CatalogMember#isUserSupplied} property of updated catalog members
 *                                           to the given value.  If not specified, the property is left unchanged.
 * @returns {Promise} A promise that resolves when the update is complete.
 */
Catalog.prototype.updateFromJson = function(json, options) {
    var that = this;
    options = defaultValue(options, {});

    return CatalogGroup.updateItems(json, options, this.group).then(function () {
        that.terria.nowViewing.sortByNowViewingIndices();
    });
};

/**
 * Serializes the catalog to JSON.
 *
 * @param {Object} [options] Object with the following properties:
 * @param {Function} [options.propertyFilter] Filter function that will be executed to determine whether a property
 *          should be serialized.
 * @param {Function} [options.itemFilter] Filter function that will be executed for each item in a group to determine
 *          whether that item should be serialized.
 * @return {Object} The serialized JSON object-literal.
 */
Catalog.prototype.serializeToJson = function(options) {
    this.terria.nowViewing.recordNowViewingIndices();

    return this.group.serializeToJson(options).items;
};

/**
 * Resolves items in the catalog based on the share keys provided, and updates them with the passed info and
 * enables them along with all their ancestors in the catalog hierarchy. This is asynchronous as it may involve a number
 * of CatalogItem#load calls.
 *
 * Note that because of the lazily-loaded nature of the catalog, items within it may not be resolvable by shareKey until
 * their parents have loaded. As a result this loads sharedObjects in serial from left to right. If a catalog member is the
 * child of an asynchronously-loaded catalog group (like a ckan or socrata group), then that group's shareKey precede the
 * child member.
 *
 * @param {Object} sharedObjects A flat map of string-based share keys with data to update on the resolved object. It is
 *      possible to pass an empty object if nothing needs updating.
 * @returns {Promise} A promise that will resolve when all the items have been loaded and enabled.
 */
Catalog.prototype.updateByShareKeys = function(sharedObjects) {
    const that = this;

    return Object.keys(sharedObjects).reduce(function(aggregatedPromise, shareKey) {
        var itemJson = sharedObjects[shareKey];

        return aggregatedPromise
            .then(this._loadInSerial.bind(this, itemJson.parents || []))
            .then(this._updateAndEnable.bind(this, shareKey, itemJson));
    }.bind(this), when()).then(() => {
        that.terria.nowViewing.sortByNowViewingIndices();
    }
    );
};

/**
 * Calls {@link CatalogMember#load} on a number of catalog members, identified by their share key, one after the other
 * from left to right. Doing this in serial is important because sometimes calling load() on a catalog group will
 * reveal more catalog items under it, which will be added to the catalog's shareKeyIndex - if these were done in
 * parallel, share keys towards the right of the array would not able to be resolved at all.
 *
 * @param shareKeys An array of catalog member share keys to use for resolving catalog members from the catalog
 * @returns {Promise} A promise that will be resolved when all the catalog members have either loaded or failed to load.
 * @private
 */
Catalog.prototype._loadInSerial = function(shareKeys) {
    return shareKeys.reduce(function(aggregatedPromise, shareKey) {
        return aggregatedPromise.then(function() {
            if (this.shareKeyIndex[shareKey]) {
                return this.shareKeyIndex[shareKey].load();
            }
        }.bind(this));
    }.bind(this), when());
};

/**
 * Finds the an item in the catalog with the passed shareKey, updates it with the passed itemJson, THEN calls load on
 * the item, THEN enables it and all its parents. If no item for the passed shareKey can be found, logs a warning but
 * proceeds without an exception.
 *
 * @returns {Promise} A promise that will be resolved when all of this is done.
 * @private
 */
Catalog.prototype._updateAndEnable = function(shareKey, itemJson) {
    var existingMember = this.shareKeyIndex[shareKey];

    if (existingMember) {
        // Update THEN load is the expected behaviour for some catalog items (e.g. CSV) - if these operations aren't
        // executed in this order then bugs happen in auto-generated legends.

        return existingMember.updateFromJson(itemJson)
            .then(existingMember.load.bind(existingMember))
            .then(existingMember.enableWithParents.bind(existingMember));
    } else {
        console.warn('Share link has a catalog member with shareKey ' + shareKey + ' but could not find ' +
            'this in the catalog');
    }
};

/**
 * If a catalog group exists with this name, update it, otherwise create it.
 * @param  {Function} CatalogGroupConstructor The constructor function for the catalog group (typically CatalogGroup).
 * @param  {String} name        The catalog group's name.
 * @param  {String} description The catalog group's description.
 * @return {CatalogGroup}       The new or updated catalog group.
 */
Catalog.prototype.upsertCatalogGroup = function(CatalogGroupConstructor, name, description) {
    var group;
    var groups = this.group.items;
    for (var i = 0; i < groups.length; ++i) {
        group = groups[i];
        if (group.name === name) {
            return group;
        }
    }
    group = new CatalogGroupConstructor(this.terria);
    group.name = name;
    group.description = description;
    group.isUserSupplied = true;
    this.group.add(group);
    return group;
};

module.exports = Catalog;