Source: lib/deprecate/enforcer.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.Enforcer');
  20. goog.require('shaka.deprecate.Version');
  23. /**
  24.  * The enforcer's job is to call the correct callback when a feature will need
  25.  * to be removed later or removed now.
  26.  *
  27.  * The "what should be done" is not part of the enforcer, that must be provided
  28.  * to the enforcer when it is created. This separation was created so that
  29.  * testing and production could be equal users of the enforcer.
  30.  *
  31.  * @final
  32.  */
  33. shaka.deprecate.Enforcer = class {
  34.   /**
  35.    * @param {!shaka.deprecate.Version} libraryVersion
  36.    * @param {shaka.deprecate.Listener} onPending
  37.    * @param {shaka.deprecate.Listener} onExpired
  38.    */
  39.   constructor(libraryVersion, onPending, onExpired) {
  40.     /** @private {!shaka.deprecate.Version} */
  41.     this.libraryVersion_ = libraryVersion;
  43.     /** @private {shaka.deprecate.Listener} */
  44.     this.onPending_ = onPending;
  45.     /** @private {shaka.deprecate.Listener} */
  46.     this.onExpired_ = onExpired;
  47.   }
  49.   /**
  50.    * Tell the enforcer that a feature will expire on |expiredOn| and that it
  51.    * should notify the listeners if it is pending or expired.
  52.    *
  53.    * @param {!shaka.deprecate.Version} expiresOn
  54.    * @param {string} name
  55.    * @param {string} description
  56.    */
  57.   enforce(expiresOn, name, description) {
  58.     // If the expiration version is larger than the library version
  59.     // (compareTo > 0), it means the expiration is in the future, and is still
  60.     // pending.
  61.     const isPending = expiresOn.compareTo(this.libraryVersion_) > 0;
  63.     // Find the right callback (pending or expired) for this enforcement request
  64.     // call it to handle this features pending/expired removal.
  65.     const callback = isPending ? this.onPending_ : this.onExpired_;
  66.     callback(this.libraryVersion_, expiresOn, name, description);
  67.   }
  68. };
  70. /**
  71.  * A callback for listening to deprecation events.
  72.  *
  73.  * Parameters:
  74.  *  libraryVersion: !shaka.deprecate.Version
  75.  *  featureVersion: !shaka.deprecate.Version
  76.  *  name: string
  77.  *  description: string
  78.  *
  79.  * libraryVersion: The current version of the library.
  80.  * featureVersion: The version of the library when the feature should be
  81.  *                 removed.
  82.  * name: The name of the feature that will/should be removed.
  83.  * description: A description of what is changing.
  84.  *
  85.  * @typedef {function(
  86.  *    !shaka.deprecate.Version,
  87.  *    !shaka.deprecate.Version,
  88.  *    string,
  89.  *    string)}
  90.  */
  91. shaka.deprecate.Listener;