AMD Loader Spec extension to support aggregation service

	// jsdoc annotations were made following these guidelines: http://code.google.com/closure/compiler/docs/js-for-compiler.html

/**
 * The loader config object
 */
require = {
  /**
     * This is an extension of the AMD loader spec to support a resource
     * aggregation service or "combo service". All loaders supporting a combo
     * service must look for configuration in the "combo" member of the loader
     * config object.
     *
     * @type {Object}
     */
  combo: {
    
    /**
     * As a loader encounters resources that it must fetch, it should first pass
     * the resource to combo.add to determine if this resource
     * can be handled by the combo service.
     *
     * If the combo service can handle the resource, it will return true, and a
     * loader must not request this resource from the server. Instead, it will
     * be requested when the combo.done function is called and
     * that function subsequently calls the load callback to
     * provide the loader with a URL that can be used to request all of the
     * modules for which combo.add returned true since the
     * preceding combo.done call, if any. If
     * combo.add returns false, then the loader should process
     * the request as normal.
     *
     * If a prefix is supplied to combo.add, and the combo
     * service chooses to handle it and returns true, the loader must not
     * process the module as handled by the plugin, but instead as a normal
     * module. This behavior is used to support combo-service plugins that are
     * handled server-side.
     *
     * @type {function(?string, string, string, !Object)}
     * @param {?string}
     *            prefix The plugin prefix of this resource, if any.
     * @param {string}
     *            name The name of the normalized name of the module being
     *            requested.
     * @param {string}
     *            url The resolved url where the loader would normally request
     *            this resource if the combo service could not handle it.
     * @param {!Object}
     *            config The loader config object, passed to the implementation
     *            of this function for reference.
     * @return {boolean} If this combo service implementation can handle the
     *         aggregation of the passed in resource.
     */
    add: function (prefix, name, url, config) {},
    
    /**
     * After a loader has called combo.add for all discovered
     * resource dependencies, the loader must call combo.done so
     * that the url to the resource aggregation may be generated by the combo
     * service.
     *
     * combo.done must call the load callback
     * passed in by the loader with an array of ordered module ids that the
     * loader will encounter when processing the loaded resource aggregation.
     * The second parameter of the load callback function is the
     * url location of where to find the resource aggregation. ex: <code>
     *   load(['example/bar'], http://foo.com/combo?query-params-go-here
     * 
     *
     * The loader loads the resource aggregation using the provided url as it
     * does with normal modules (e.g. by inserting a <script> tag into the
     * document with the url as the value of the "src" attribute).
     *
     * The loaded resource aggregation will be a javascript page consisting of
     * the concatenation of the contents of the requested modules in the order
     * specified by the first parameter to the load callback (the array of
     * module ids). The array of module ids is provided to provide the loader
     * with the ability to identify anonymous modules in the resource
     * aggregation.
     *
     * @type {function(function, Object)}
     * @param {function(Array.
     *            , string)} load The callback that done
     *            must call in order to complete the load for resources
     *            identified by the loader.
     * @param {Object}
     *            config The loader config object, passed to the implementation
     *            of this function for reference.
     */
    done: function(load, config){},
    
    /**
     * This object represents all of the plugins that the implementation of this
     * combo service wishes to reserve. These plugins are not normal loader
     * plugins and should not be processed as such. They are meant to be used to
     * enable server-side combo plugins.
     *
     * ex: <code>combo/text!example/resources/foo.txt</code>
     *
     * A loader wishing to load this resource must not process the plugin as a
     * regular loader plugin if <code>combo.plugins</code> contains a truthy
     * mapping for the plugin in question. ex: <code>
     * combo: {
     *   plugins: {
     *     'combo/text': 1
     *   }
     * }
     * </code>
     *
     * A resulting call to combo.add would look like
     * <code>combo.add('combo/text', 'example/resources/foo.txt', ...)</code>
     * and must return true;
     * 
     * All implementations of this API are expected to support the "combo/text" plugin  
     * name.  Implementations may provide support for additional plugin names to 
     * specify special processing of module content, or to support loading non-text
     * resources (e.g. images).
     *
     * @type {Object.<string, ?(number|string|boolean|Object)>}
     */
    plugins: {};

    /**
     * This method returns true if the specified module can be provided by the
     * aggregation service.  It is provided primarily for loader plugins that
     * wish to leverage the aggregation service.  A text loader plugin could delegate
     * to the aggregation service using the combo plugin id for loading text modules.
     * For example:<code>
     * load: function(mid, require, load) {
     *   var url = require.toUrl(mid);
     *   if (require.combo && "combo/text" in require.combo.plugins && 
     *       require.combo.isSupportedModule(mid, url)) {
     *     // Delegate to aggregation service
     *     require(["combo/text!"+mid], function(text) {
     *       load(text);
     *     });
     *   } else {
     *     // Load module as normal...
     *   }
     * }</code>
     *
     * @type {function(string, string)}
     * @param {string} 
     *            the module id 
     * @param {string}
     *            the resolved url for the module
     * @return {boolean} True if the specified module can be provided by the
     *     aggregation service.
     */
    isSupportedModule(mid, url) {}
  }
}