added support for the depth query parameter in the remote API.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@6541 71c3de6d-444a-0410-be80-ed276b4c234a

core/pom.xml

@@ -272,7 +272,7 @@
     <dependency>
       <groupId>org.kohsuke.stapler</groupId>
       <artifactId>stapler</artifactId>
-      <version>1.56</version>
+      <version>1.57</version>
     </dependency>
     <dependency>
       <groupId>org.kohsuke</groupId>

core/src/main/java/hudson/model/Api.java

@@ -52,7 +52,10 @@ public class Api extends AbstractModelObject {
     /**
      * Exposes the bean as XML.
      */
-    public void doXml(StaplerRequest req, StaplerResponse rsp, @QueryParameter("xpath") String xpath, @QueryParameter("wrapper") String wrapper) throws IOException, ServletException {
+    public void doXml(StaplerRequest req, StaplerResponse rsp,
+                      @QueryParameter("xpath") String xpath,
+                      @QueryParameter("wrapper") String wrapper,
+                      @QueryParameter("depth") int depth) throws IOException, ServletException {
         if(xpath==null) {
             // serve the whole thing
             rsp.serveExposedBean(req,bean,Flavor.XML);
@@ -63,7 +66,7 @@ public class Api extends AbstractModelObject {
 
         // first write to String
         Model p = MODEL_BUILDER.get(bean.getClass());
-        p.writeTo(bean,Flavor.XML.createDataWriter(bean,sw));
+        p.writeTo(bean,depth,Flavor.XML.createDataWriter(bean,sw));
 
         // apply XPath
         Object result;

core/src/main/resources/hudson/model/Api/index.jelly

@@ -36,6 +36,16 @@
         <a href="http://hudson.gotdns.com/wiki/display/HUDSON/Remote+access+API">the documentation</a>.
       </p>
 
+      <h2>Controling the amount of data you fetch</h2>
+      <p>
+        In both formats, the <tt>depth</tt> query parameter can be used to control the amount of data
+        you'll receive. The default is <tt>depth=0</tt>, but by increasing this value you can get
+        a lot of data by single remote API invocation (the downside is bigger bandwidth requirement.)
+        Compare <a href="xml">depth=0</a> and <a href="xml?depth=1">depth=1</a> and see what the difference
+        is for yourself. Also note that data created by a smaller depth value is always a subset of
+        the data created by a bigger depth value.
+      </p>
+
       <st:include it="${it.bean}" page="_api.jelly" optional="true" />
     </l:main-panel>
 	</l:layout>