From db32ad92936b206710aff5f9827bde7a5856328d Mon Sep 17 00:00:00 2001
From: Kohsuke Kawaguchi <kk@kohsuke.org>
Date: Fri, 27 Jul 2012 11:43:25 +0900
Subject: [PATCH] Exposing more REST API from update center and writing docs

---
 .../main/java/hudson/model/UpdateCenter.java  | 11 +++-
 .../main/java/hudson/model/UpdateSite.java    | 12 ++++
 .../hudson/model/UpdateCenter/_api.jelly      | 57 +++++++++++++++++++
 3 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 core/src/main/resources/hudson/model/UpdateCenter/_api.jelly

diff --git a/core/src/main/java/hudson/model/UpdateCenter.java b/core/src/main/java/hudson/model/UpdateCenter.java
index 9812192921..527b097fe1 100644
--- a/core/src/main/java/hudson/model/UpdateCenter.java
+++ b/core/src/main/java/hudson/model/UpdateCenter.java
@@ -213,11 +213,18 @@ public class UpdateCenter extends AbstractModelObject implements Saveable, OnMas
      * @return
      *      can be empty but never null.
      */
-    @Exported
     public PersistedList<UpdateSite> getSites() {
         return sites;
     }
 
+    /**
+     * The same as {@link #getSites()} but for REST API.
+     */
+    @Exported(name="sites")
+    public List<UpdateSite> getSiteList() {
+        return sites.toList();
+    }
+
     public UpdateSite getSite(String id) {
         for (UpdateSite site : sites)
             if (site.getId().equals(id))
@@ -971,7 +978,6 @@ public class UpdateCenter extends AbstractModelObject implements Saveable, OnMas
         /**
          * Get the user that initiated this job
          */
-        @Exported
         public Authentication getUser() {
             return this.authentication;
         }
@@ -1031,6 +1037,7 @@ public class UpdateCenter extends AbstractModelObject implements Saveable, OnMas
          * <p>
          * Instances of this class is immutable.
          */
+        @ExportedBean
         public abstract class InstallationStatus extends Throwable {
             public final int id = iota.incrementAndGet();
             @Exported
diff --git a/core/src/main/java/hudson/model/UpdateSite.java b/core/src/main/java/hudson/model/UpdateSite.java
index f2d3b1a974..3282ba9467 100644
--- a/core/src/main/java/hudson/model/UpdateSite.java
+++ b/core/src/main/java/hudson/model/UpdateSite.java
@@ -95,6 +95,7 @@ import static hudson.util.TimeUnit2.*;
  * @author Kohsuke Kawaguchi
  * @since 1.333
  */
+@ExportedBean
 public class UpdateSite {
     /**
      * What's the time stamp of data file?
@@ -153,10 +154,12 @@ public class UpdateSite {
     /**
      * Get ID string.
      */
+    @Exported
     public String getId() {
         return id;
     }
 
+    @Exported
     public long getDataTimestamp() {
         return dataTimestamp;
     }
@@ -367,6 +370,7 @@ public class UpdateSite {
      * Returns a list of plugins that should be shown in the "available" tab.
      * These are "all plugins - installed plugins".
      */
+    @Exported
     public List<Plugin> getAvailables() {
         List<Plugin> r = new ArrayList<Plugin>();
         Data data = getData();
@@ -393,9 +397,14 @@ public class UpdateSite {
         return dt.plugins.get(artifactId);
     }
 
+    public Api getApi() {
+        return new Api(this);
+    }
+
     /**
      * Returns an "always up" server for Internet connectivity testing, or null if we are going to skip the test.
      */
+    @Exported
     public String getConnectionCheckUrl() {
         Data dt = getData();
         if(dt==null)    return "http://www.google.com/";
@@ -416,6 +425,7 @@ public class UpdateSite {
      * @return
      *      can be empty but never null.
      */
+    @Exported
     public List<Plugin> getUpdates() {
         Data data = getData();
         if(data==null)      return Collections.emptyList(); // fail to determine
@@ -432,6 +442,7 @@ public class UpdateSite {
     /**
      * Does any of the plugin has updates?
      */
+    @Exported
     public boolean hasUpdates() {
         Data data = getData();
         if(data==null)      return false;
@@ -450,6 +461,7 @@ public class UpdateSite {
      * Exposed to get rid of hardcoding of the URL that serves up update-center.json
      * in Javascript.
      */
+    @Exported
     public String getUrl() {
         return url;
     }
diff --git a/core/src/main/resources/hudson/model/UpdateCenter/_api.jelly b/core/src/main/resources/hudson/model/UpdateCenter/_api.jelly
new file mode 100644
index 0000000000..503c271430
--- /dev/null
+++ b/core/src/main/resources/hudson/model/UpdateCenter/_api.jelly
@@ -0,0 +1,57 @@
+<!--
+The MIT License
+
+Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Simon Wiest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
+<?jelly escape-by-default='true'?>
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form" xmlns:i="jelly:fmt">
+  <h2>Accessing Update Sites</h2>
+  <p>
+    Update center is a collection of update sites. The "main" update site that contains Jenkins update
+    can be accessed from <a href="../coreSource/api">here</a>. Otherwise you can obtain update center
+    by its ID:
+  </p>
+  <ul>
+    <j:forEach var="site" items="${it.sites}">
+      <li>
+        <a href="../site/${site.id}/api">${site.id}</a>
+      </li>
+    </j:forEach>
+  </ul>
+  <a href="json?tree=sites[id,url]">This data can be retrieved in a form more accessible for programs</a>, too.
+
+  <h2>Update Center Jobs</h2>
+  <p>
+    Once a plugin installation/update, and core update is requested, these tasks are recorded in the update center
+    and get executed in turn. Jenkins calls them "update center jobs". The current list of jobs are as follows:
+  </p>
+  <ul>
+    <j:forEach var="j" items="${it.jobs}" varStatus="loop">
+      <li>
+        <a href="../jobs/${loop.index}/api">${j}</a>
+      </li>
+    </j:forEach>
+  </ul>
+  <p>
+    Each job exposes its own set of APIs.
+  </p>
+</j:jelly>
\ No newline at end of file
-- 
GitLab