Allow the tree parameter and the xpath parameter to be used together …

…in the REST API.

Previously, the presence of the xpath parameter suppressed the tree
parameter processing. This change fixes that so that the tree parameter
can be used for building small DOM, then XPath to manipulate the data
further.

changelog.html

@@ -100,6 +100,8 @@
   <li class=rfe>
     Added a new extension point for custom checkout behaviour, especially targeted for matrix projects.
     (<a href="https://github.com/jenkinsci/jenkins/pull/482">pull 482</a>)
+  <li class=rfe>
+    Allow the tree parameter and the xpath parameter to be used together in the REST API.
   <li class=rfe>
     Enabled concurrent build support for matrix projects
     (<a href="https://issues.jenkins-ci.org/browse/JENKINS-6747">issue 6747</a>)

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

@@ -35,6 +35,7 @@
 import org.kohsuke.stapler.StaplerRequest;
 import org.kohsuke.stapler.StaplerResponse;
 import org.kohsuke.stapler.export.*;
+import org.kohsuke.stapler.export.TreePruner.ByDepth;
 
 import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletResponse;
@@ -79,6 +80,7 @@ public String getSearchUrl() {
     public void doXml(StaplerRequest req, StaplerResponse rsp,
                       @QueryParameter String xpath,
                       @QueryParameter String wrapper,
+                      @QueryParameter String tree,
                       @QueryParameter int depth) throws IOException, ServletException {
         String[] excludes = req.getParameterValues("exclude");
 
@@ -92,7 +94,8 @@ public void doXml(StaplerRequest req, StaplerResponse rsp,
 
         // first write to String
         Model p = MODEL_BUILDER.get(bean.getClass());
-        p.writeTo(bean,depth,Flavor.XML.createDataWriter(bean,sw));
+        TreePruner pruner = (tree!=null) ? new NamedPathPruner(tree) : new ByDepth(1 - depth);
+        p.writeTo(bean,pruner,Flavor.XML.createDataWriter(bean,sw));
 
         // apply XPath
         Object result;

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

@@ -48,13 +48,21 @@ THE SOFTWARE.
 
             For XPath that matches multiple nodes, you need to also specify the "wrapper" query parameter
             to specify the name of the root XML element to be create so that the resulting XML becomes well-formed.
-         </p>
+          </p>
           <p>
             Similarly <tt>exclude</tt> query parameter can be used to exclude nodes
             that match the given XPath from the result. This is useful for
             trimming down the amount of data you fetch (but again see <a href="#tree">below</a>). This query parameter can be specified
             multiple times.
           </p>
+          <p>
+            XPath filtering is powerful, and you can have it only return a very small data, but note that
+            the server still has to build a full DOM of the raw data, which could cause a large memory spike.
+            To avoid overloading the server, consider using the <tt>tree</tt> parameter, or use the <tt>xpath</tt> parameter
+            in conjunction with the <tt>tree</tt> parameter. When used together, the result of the <tt>tree</tt> parameter
+            filtering is built into DOM, then the XPath is applied to compute the final return value. In this way,
+            you can often substantially reduce the size of DOM built in memory.
+          </p>
         </dd>
 
         <dt><a href="json">JSON API</a></dt>