Fixed #104

 o Added consistently QueueReference as return type to
   all build methods of the Job class.

Author: khmarbaise

ReleaseNotes.md

@@ -14,6 +14,19 @@
 
 ### API Changes
 
+ * [Fixed Issue 104][issue-104] all build* methods now return consistently `QueueReference` 
+   to make it possible to query for a queued build and if a build from the queue has
+   been cancelled or to see if a build is running.
+ 
+```java
+ public class Job extends BaseModel {
+   public QueueReference build();
+   public QueueReference build(boolean crumbFlag);
+   public QueueReference build(Map<String, String> params);
+   public QueueReference build(Map<String, String> params, boolean crumbFlag);
+}
+```
+
  * [Fixed Issue 203][issue-203] with [pull request #204][pull-204]
    of RainerW <[email protected]>
 
@@ -682,6 +695,7 @@ TestReport testReport = mavenJob.getLastSuccessfulBuild().getTestReport();
 [issue-104]: https://github.com/jenkinsci/java-client-api/issues/104
 [issue-111]: https://github.com/jenkinsci/java-client-api/issues/111
 [issue-116]: https://github.com/jenkinsci/java-client-api/issues/116
+[issue-104]: https://github.com/jenkinsci/java-client-api/issues/104
 [issue-108]: https://github.com/jenkinsci/java-client-api/issues/108
 [issue-113]: https://github.com/jenkinsci/java-client-api/issues/113
 [issue-119]: https://github.com/jenkinsci/java-client-api/issues/119

jenkins-client/src/main/java/com/offbytwo/jenkins/JenkinsServer.java

@@ -714,17 +714,18 @@ public String runScript(String script) throws IOException {
     }
 
     public Queue getQueue() throws IOException {
+        //TODO: Check if using depth=1 is a good idea?
         return client.get("queue/?depth=1", Queue.class);
     }
 
     public QueueItem getQueueItem(QueueReference ref) throws IOException {
         try {
             String url = ref.getQueueItemUrlPart();
             // "/queue/item/" + id
-            QueueItem job = client.get(url, QueueItem.class);
-            job.setClient(client);
+            QueueItem queueItem = client.get(url, QueueItem.class);
+            queueItem.setClient(client);
 
-            return job;
+            return queueItem;
         } catch (HttpResponseException e) {
             if (e.getStatusCode() == HttpStatus.SC_NOT_FOUND) {
                 return null;

jenkins-client/src/main/java/com/offbytwo/jenkins/model/Job.java

@@ -48,13 +48,14 @@ public JobWithDetails details() throws IOException {
     /**
      * Get a file from workspace.
      * 
-     * @param fileName The name of the file to download from workspace.
-     *  You can also access files which are in sub folders of the workspace.
+     * @param fileName
+     *            The name of the file to download from workspace. You can also
+     *            access files which are in sub folders of the workspace.
      * @return The string which contains the content of the file.
      * @throws IOException
      */
     public String getFileFromWorkspace(String fileName) throws IOException {
-        InputStream is = client.getFile( URI.create( url + "/ws/" + fileName ));
+        InputStream is = client.getFile(URI.create(url + "/ws/" + fileName));
         ByteArrayOutputStream result = new ByteArrayOutputStream();
         byte[] buffer = new byte[1024];
         int length;
@@ -66,30 +67,44 @@ public String getFileFromWorkspace(String fileName) throws IOException {
 
     /**
      * Trigger a build without parameters
+     * 
+     * @return {@link QueueReference} for further analysis of the queued build.
+     * @throws IOException
+     *             in case of an error.
      */
-    public void build() throws IOException {
-        client.post(url + "build");
+    public QueueReference build() throws IOException {
+        ExtractHeader location = client.post(url + "build", null, ExtractHeader.class, false);
+        return new QueueReference(location.getLocation());
+
     }
 
     /**
      * Trigger a build with crumbFlag.
-     * @param crumbFlag true or false.
-     * @throws IOException in case of an error.
+     * 
+     * @param crumbFlag
+     *            true or false.
+     * @return {@link QueueReference} for further analysis of the queued build.
+     * @throws IOException
+     *             in case of an error.
      */
-    public void build(boolean crumbFlag) throws IOException {
-        client.post(url + "build", crumbFlag);
+    public QueueReference build(boolean crumbFlag) throws IOException {
+        ExtractHeader location = client.post(url + "build", null, ExtractHeader.class, crumbFlag);
+        return new QueueReference(location.getLocation());
     }
 
     /**
      * Trigger a parameterized build
      *
      * @param params
      *            the job parameters
+     * @return {@link QueueReference} for further analysis of the queued build.
      * @throws IOException
      */
-    public void build(Map<String, String> params) throws IOException {
+    public QueueReference build(Map<String, String> params) throws IOException {
         String qs = join(Collections2.transform(params.entrySet(), new MapEntryToQueryStringPair()), "&");
         client.post(url + "buildWithParameters?" + qs);
+        ExtractHeader location = client.post(url + "buildWithParameters?" + qs, null, ExtractHeader.class, false);
+        return new QueueReference(location.getLocation());
     }
 
     /**
@@ -99,6 +114,7 @@ public void build(Map<String, String> params) throws IOException {
      *            the job parameters
      * @param crumbFlag
      *            determines whether crumb flag is used
+     * @return {@link QueueReference} for further analysis of the queued build.
      * @throws IOException
      */
     public QueueReference build(Map<String, String> params, boolean crumbFlag) throws IOException {