Source: lib/deprecate/deprecate.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.Deprecate');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.deprecate.Enforcer');
  22. goog.require('shaka.deprecate.Version');
  25. /**
  26.  * |shaka.Deprecate| is the front-end of the deprecation system, allowing for
  27.  * any part of the code to say that "this block of code should be removed by
  28.  * version X".
  29.  *
  30.  * @final
  31.  */
  32. shaka.Deprecate = class {
  33.   /**
  34.    * Initialize the system. This must happen before any calls to |enforce|. In
  35.    * our code base, |shaka.Player| will be the only one to call this (it has the
  36.    * version string).
  37.    *
  38.    * If the |Deprecate| called |Player.version| to initialize itself, it would
  39.    * mean that |Player| could not use |Deprecate| because it would create a
  40.    * circular dependency. To work around this, we provide this method so that
  41.    * |Player| can give us the version without us needing to know about |Player|.
  42.    *
  43.    * This will initialize the system to:
  44.    *  - print warning messages when the feature is scheduled to be removed in a
  45.    *    later version
  46.    *  - print errors and fail assertions when the feature should be removed now
  47.    *
  48.    * @param {string} versionString
  49.    */
  50.   static init(versionString) {
  51.     goog.asserts.assert(
  52.         shaka.Deprecate.enforcer_ == null,
  53.         'Deprecate.init should only be called once.');
  55.     shaka.Deprecate.enforcer_ = new shaka.deprecate.Enforcer(
  56.         shaka.deprecate.Version.parse(versionString),
  57.         shaka.Deprecate.onPending_,
  58.         shaka.Deprecate.onExpired_);
  59.   }
  61.   /**
  62.    * Ask the deprecation system to require this feature to be removed by the
  63.    * given version.
  64.    *
  65.    * @param {number} major
  66.    * @param {number} minor
  67.    * @param {string} name
  68.    * @param {string} description
  69.    */
  70.   static deprecateFeature(major, minor, name, description) {
  71.     const enforcer = shaka.Deprecate.enforcer_;
  72.     goog.asserts.assert(
  73.         enforcer,
  74.         'Missing deprecation enforcer. Was |init| called?');
  76.     const expiresAt = new shaka.deprecate.Version(major, minor);
  77.     enforcer.enforce(expiresAt, name, description);
  78.   }
  80.   /**
  81.    * @param {!shaka.deprecate.Version} libraryVersion
  82.    * @param {!shaka.deprecate.Version} featureVersion
  83.    * @param {string} name
  84.    * @param {string} description
  85.    * @private
  86.    */
  87.   static onPending_(libraryVersion, featureVersion, name, description) {
  88.     // If we were to pass each value to the log call, it would be printed as
  89.     // a comma-separated list. To make the print state appear more natural to
  90.     // the reader, create one string for the message.
  91.     shaka.log.alwaysWarn([
  92.       name,
  93.       'has been deprecated and will be removed in',
  94.       featureVersion,
  95.       '. We are currently at version',
  96.       libraryVersion,
  97.       '. Additional information:',
  98.       description,
  99.     ].join(' '));
  100.   }
  102.   /**
  103.    * @param {!shaka.deprecate.Version} libraryVersion
  104.    * @param {!shaka.deprecate.Version} featureVersion
  105.    * @param {string} name
  106.    * @param {string} description
  107.    * @private
  108.    */
  109.   static onExpired_(libraryVersion, featureVersion, name, description) {
  110.     // If we were to pass each value to the log call, it would be printed as
  111.     // a comma-separated list. To make the print state appear more natural to
  112.     // the reader, create one string for the message.
  113.     const errorMessage = [
  114.       name,
  115.       'has been deprecated and has been removed in',
  116.       featureVersion,
  117.       '. We are now at version',
  118.       libraryVersion,
  119.       '. Additional information:',
  120.       description,
  121.     ].join('');
  123.     shaka.log.alwaysError(errorMessage);
  124.     goog.asserts.assert(false, errorMessage);
  125.   }
  126. };
  128. /**
  129.  * The global deprecation enforcer that will be set by the player (because the
  130.  * player knows the version) when it calls |init|. This may appear a little
  131.  * round-about to you, because it is. Since player uses |Deprecate|, it means
  132.  * that |Deprecate| can't depend on Player directly.
  133.  *
  134.  * @private {shaka.deprecate.Enforcer}
  135.  */
  136. shaka.Deprecate.enforcer_ = null;