From a1b5ec15326bc7ff72f080d8c4b962bad7ca5dfe Mon Sep 17 00:00:00 2001
From: Tim Van Holder <tim.vanholder@gmail.com>
Date: Mon, 6 Jul 2020 08:52:53 +0200
Subject: [PATCH] JENKINS-62572: Extend Downloadable API slightly (#4773)

---
 .../java/hudson/model/DownloadService.java    | 82 ++++++++++++++++---
 1 file changed, 71 insertions(+), 11 deletions(-)

diff --git a/core/src/main/java/hudson/model/DownloadService.java b/core/src/main/java/hudson/model/DownloadService.java
index dfdd4e5c7a..dc4f256b5e 100644
--- a/core/src/main/java/hudson/model/DownloadService.java
+++ b/core/src/main/java/hudson/model/DownloadService.java
@@ -23,6 +23,8 @@
  */
 package hudson.model;
 
+import edu.umd.cs.findbugs.annotations.CheckForNull;
+import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Extension;
 import hudson.ExtensionList;
 import hudson.ExtensionListListener;
@@ -205,7 +207,9 @@ public class DownloadService {
         private volatile long lastAttempt=Long.MIN_VALUE;
 
         /**
+         * Creates a new downloadable.
          *
+         * @param id The ID to use.
          * @param url
          *      URL relative to {@link UpdateCenter#getDefaultBaseUrl()}.
          *      So if this string is "foo.json", the ultimate URL will be
@@ -213,38 +217,77 @@ public class DownloadService {
          *
          *      For security and privacy reasons, we don't allow the retrieval
          *      from random locations.
+         * @param interval The interval, in milliseconds, between attempts to update this downloadable's data.
          */
-        public Downloadable(String id, String url, long interval) {
+        public Downloadable(@NonNull String id, @NonNull String url, long interval) {
             this.id = id;
             this.url = url;
             this.interval = interval;
         }
 
+        /**
+         * Creates a new downloadable.
+         * This will generate an ID based on this downloadable's class (using {@link #idFor(Class)}. The URL will be set
+         * to that ID, with an added {@code .json} extension, and the default interval will be used.
+         */
         public Downloadable() {
-            this.id = getClass().getName().replace('$','.');
-            this.url = this.id+".json";
+            this.id = Downloadable.idFor(this.getClass());
+            this.url = this.id + ".json";
             this.interval = DEFAULT_INTERVAL;
         }
 
         /**
-         * Uses the class name as an ID.
+         * Creates a new downloadable.
+         * This will generate an ID based on the specified class (using {@link #idFor(Class)}. The URL will be set to
+         * that ID, with an added {@code .json} extension, and the default interval will be used.
+         *
+         * @param clazz The class to use to generate the ID.
          */
-        public Downloadable(Class id) {
-            this(id.getName().replace('$','.'));
+        public Downloadable(@NonNull Class<?> clazz) {
+            this(Downloadable.idFor(clazz));
         }
 
-        public Downloadable(String id) {
-            this(id,id+".json");
+        /**
+         * Creates a new downloadable with a specific ID. The URL will be set to that ID, with an added {@code .json}
+         * extension, and the default interval will be used.
+         *
+         * @param id The ID to use.
+         */
+        public Downloadable(@NonNull String id) {
+            this(id, id + ".json");
         }
 
-        public Downloadable(String id, String url) {
-            this(id,url, DEFAULT_INTERVAL);
+        /**
+         * Creates a new downloadable with a specific ID and URL. The default interval will be used.
+         *
+         * @param id  The ID to use.
+         * @param url URL relative to {@link UpdateCenter#getDefaultBaseUrl()}. So if this string is "foo.json", the
+         *            ultimate URL will be something like "http://updates.jenkins-ci.org/updates/foo.json".
+         *            <p>
+         *            For security and privacy reasons, we don't allow the retrieval from random locations.
+         */
+        public Downloadable(@NonNull String id, @NonNull String url) {
+            this(id, url, DEFAULT_INTERVAL);
         }
 
+        @NonNull
         public String getId() {
             return id;
         }
 
+        /**
+         * Generates an ID based on a class.
+         *
+         * @param clazz The class to use to generate an ID.
+         * @return The ID generated based on the specified class.
+         *
+         * @since TODO
+         */
+        @NonNull
+        public static String idFor(@NonNull Class<?> clazz) {
+            return clazz.getName().replace('$','.');
+        }
+
         /**
          * URL to download.
          */
@@ -406,13 +449,30 @@ public class DownloadService {
         /**
          * Returns all the registered {@link Downloadable}s.
          */
+        @NonNull
         public static ExtensionList<Downloadable> all() {
             return ExtensionList.lookup(Downloadable.class);
         }
 
         /**
-         * Returns the {@link Downloadable} that has the given ID.
+         * Returns the {@link Downloadable} that has an ID associated with the specified class (as computed via
+         * {@link #idFor(Class)}).
+         *
+         * @param clazz The class to use to determine the downloadable's ID.
+         *
+         * @since TODO
          */
+        @CheckForNull
+        public static Downloadable get(@NonNull Class<?> clazz) {
+            return Downloadable.get(Downloadable.idFor(clazz));
+        }
+
+        /**
+         * Returns the {@link Downloadable} that has the given ID.
+         *
+         * @param id The ID to look for.
+         */
+        @CheckForNull
         public static Downloadable get(String id) {
             for (Downloadable d : all()) {
                 if(d.id.equals(id))