Source: lib/deprecate/deprecate.js

  1. /*! @license
  2. * Shaka Player
  3. * Copyright 2016 Google LLC
  4. * SPDX-License-Identifier: Apache-2.0
  5. */
  6. goog.provide('shaka.Deprecate');
  7. goog.require('goog.asserts');
  8. goog.require('shaka.deprecate.Enforcer');
  9. goog.require('shaka.deprecate.Version');
  10. goog.require('shaka.log');
  11. /**
  12. * |shaka.Deprecate| is the front-end of the deprecation system, allowing for
  13. * any part of the code to say that "this block of code should be removed by
  14. * version X".
  15. *
  16. * @final
  17. */
  18. shaka.Deprecate = class {
  19. /**
  20. * Initialize the system. This must happen before any calls to |enforce|. In
  21. * our code base, |shaka.Player| will be the only one to call this (it has the
  22. * version string).
  23. *
  24. * If the |Deprecate| called |Player.version| to initialize itself, it would
  25. * mean that |Player| could not use |Deprecate| because it would create a
  26. * circular dependency. To work around this, we provide this method so that
  27. * |Player| can give us the version without us needing to know about |Player|.
  28. *
  29. * This will initialize the system to:
  30. * - print warning messages when the feature is scheduled to be removed in a
  31. * later version
  32. * - print errors and fail assertions when the feature should be removed now
  33. *
  34. * @param {string} versionString
  35. */
  36. static init(versionString) {
  37. goog.asserts.assert(
  38. shaka.Deprecate.enforcer_ == null,
  39. 'Deprecate.init should only be called once.');
  40. shaka.Deprecate.enforcer_ = new shaka.deprecate.Enforcer(
  41. shaka.deprecate.Version.parse(versionString),
  42. shaka.Deprecate.onPending_,
  43. shaka.Deprecate.onExpired_);
  44. }
  45. /**
  46. * Ask the deprecation system to require this feature to be removed by the
  47. * given version.
  48. *
  49. * @param {number} major
  50. * @param {string} name
  51. * @param {string} description
  52. */
  53. static deprecateFeature(major, name, description) {
  54. const enforcer = shaka.Deprecate.enforcer_;
  55. goog.asserts.assert(
  56. enforcer,
  57. 'Missing deprecation enforcer. Was |init| called?');
  58. const expiresAt = new shaka.deprecate.Version(major, 0);
  59. enforcer.enforce(expiresAt, name, description);
  60. }
  61. /**
  62. * @param {!shaka.deprecate.Version} libraryVersion
  63. * @param {!shaka.deprecate.Version} featureVersion
  64. * @param {string} name
  65. * @param {string} description
  66. * @private
  67. */
  68. static onPending_(libraryVersion, featureVersion, name, description) {
  69. // If we were to pass each value to the log call, it would be printed as
  70. // a comma-separated list. To make the print state appear more natural to
  71. // the reader, create one string for the message.
  72. shaka.log.alwaysWarn([
  73. name,
  74. 'has been deprecated and will be removed in',
  75. featureVersion,
  76. '. We are currently at version',
  77. libraryVersion,
  78. '. Additional information:',
  79. description,
  80. ].join(' '));
  81. }
  82. /**
  83. * @param {!shaka.deprecate.Version} libraryVersion
  84. * @param {!shaka.deprecate.Version} featureVersion
  85. * @param {string} name
  86. * @param {string} description
  87. * @private
  88. */
  89. static onExpired_(libraryVersion, featureVersion, name, description) {
  90. // If we were to pass each value to the log call, it would be printed as
  91. // a comma-separated list. To make the print state appear more natural to
  92. // the reader, create one string for the message.
  93. const errorMessage = [
  94. name,
  95. 'has been deprecated and has been removed in',
  96. featureVersion,
  97. '. We are now at version',
  98. libraryVersion,
  99. '. Additional information:',
  100. description,
  101. ].join(' ');
  102. shaka.log.alwaysError(errorMessage);
  103. goog.asserts.assert(false, errorMessage);
  104. }
  105. };
  106. /**
  107. * The global deprecation enforcer that will be set by the player (because the
  108. * player knows the version) when it calls |init|. This may appear a little
  109. * round-about to you, because it is. Since player uses |Deprecate|, it means
  110. * that |Deprecate| can't depend on Player directly.
  111. *
  112. * @private {shaka.deprecate.Enforcer}
  113. */
  114. shaka.Deprecate.enforcer_ = null;