Fixed #209

 Return TestReport.NO_TEST_REPORT etc.

Author: khmarbaise

ReleaseNotes.md

@@ -16,6 +16,53 @@
 
 ### API Changes
 
+
+  * [Fixed issue 209][issue-209]
+  
+    Consider Returning null from the "getTestReport()" of Build.java class for builds that Never run.
+    
+    The type `BUILD_HAS_NEVER_RUN` has been enhanced to return `TestReport.NO_TEST_REPORT` if you
+    call `getTestReport()` and return `BuildWithDetails.BUILD_HAS_NEVER_RUN` if you call `details()` on the 
+    type.
+    
+    Furthermore `JobWithDetails` class has been enhanced with the following methods:
+    
+```java
+public class JobWithDetails ... {
+    public boolean hasFirstBuildRun();
+    public boolean hasLastBuildRun(;
+    public boolean hasLastCompletedBuildRun();
+    public boolean hasLastFailedBuildRun();
+    public boolean hasLastStableBuildRun();
+    public boolean hasLastSuccessfulBuildRun();
+    public boolean hasLastUnstableBuildRun();
+    public boolean hasLastUnsuccessfulBuildRun();
+}
+```
+   to make checking more convenient. The following code snippet
+   shows how you need to go before this change:
+   
+```java
+JobWithDetails job = server.getJob(jobName);
+if (Build.BUILD_HAS_NEVER_RUN.equals(job.getLastBuild()) {
+  ...
+} else {
+  // Now we can get the TestReport
+  job.getLastBuild().getTestReport();
+}
+```
+
+   This can now be simplified to the following:
+   
+```java
+JobWithDetails job = server.getJob(jobName);
+if (job.hasLastBuildRun()) {
+  // Now we can get the TestReport
+  job.getLastBuild().getTestReport();
+} else {
+}
+```
+
   * [Fixed issue 211][issue-211]
 
     Added methods to update/clear the description of a job.
@@ -787,6 +834,7 @@ TestReport testReport = mavenJob.getLastSuccessfulBuild().getTestReport();
 [issue-202]: https://github.com/jenkinsci/java-client-api/issues/202
 [issue-203]: https://github.com/jenkinsci/java-client-api/issues/203
 [issue-207]: https://github.com/jenkinsci/java-client-api/issues/207
+[issue-209]: https://github.com/jenkinsci/java-client-api/issues/209
 [issue-211]: https://github.com/jenkinsci/java-client-api/issues/211
 [pull-123]: https://github.com/jenkinsci/java-client-api/pull/123
 [pull-149]: https://github.com/jenkinsci/java-client-api/pull/149

jenkins-client-it-docker/src/test/java/com/offbytwo/jenkins/integration/NoExecutorStartedGetJobIT.java

@@ -79,6 +79,11 @@ public void getLastFailedBuildShouldBeBUILD_HAS_NEVER_RAN() {
         assertThat(job.getLastFailedBuild()).isEqualTo(Build.BUILD_HAS_NEVER_RUN);
     }
 
+    @Test
+    public void hasLastFailedBuildShouldBeTrue() {
+        assertThat(job.hasLastFailedBuildRun()).isTrue();
+    }
+    
     @Test
     public void getLastStableBuildShouldNotBeNull() throws IOException {
         assertThat(job.getLastStableBuild()).isNotNull();

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

@@ -14,14 +14,38 @@ public class Build extends BaseModel {
 
     /**
      * This will be returned by the API in cases where no build has ever been
-     * executed like {@link JobWithDetails#getLastBuild()} etc.
+     * executed like {@link JobWithDetails#getLastBuild()} etc. This will also
+     * be returned by {@link #details()} is the build has not been run.
      */
-    public static final Build BUILD_HAS_NEVER_RUN = new Build(-1, -1, "UNKNOWN");
+    public static final Build BUILD_HAS_NEVER_RUN = new Build(-1, -1, "UNKNOWN") {
+        @Override
+        public TestReport getTestReport() {
+            return TestReport.NO_TEST_REPORT;
+        }
+
+        @Override
+        public BuildWithDetails details() {
+            // For a build which never has been run you couldn't get
+            // details about!
+            return BuildWithDetails.BUILD_HAS_NEVER_RUN;
+        }
+    };
+
     /**
      * This will be returned by the API in cases where a build has been
      * cancelled.
      */
-    public static final Build BUILD_HAS_BEEN_CANCELLED = new Build(-1, -1, "CANCELLED");
+    public static final Build BUILD_HAS_BEEN_CANCELLED = new Build(-1, -1, "CANCELLED") {
+        @Override
+        public TestReport getTestReport() {
+            return TestReport.NO_TEST_REPORT;
+        }
+
+        @Override
+        public BuildWithDetails details() {
+            return BuildWithDetails.BUILD_HAS_BEEN_CANCELLED;
+        }
+    };
 
     private int number;
     private int queueId;
@@ -70,6 +94,13 @@ protected void setUrl(String url) {
         this.url = url;
     }
 
+    /**
+     * 
+     * @return The information from Jenkins. In cases the build has never run
+     *         {@link #BUILD_HAS_NEVER_RUN} will be returned.
+     * @throws IOException
+     *             in case of an error.
+     */
     public BuildWithDetails details() throws IOException {
         return client.get(url, BuildWithDetails.class);
     }

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

@@ -7,10 +7,26 @@
 package com.offbytwo.jenkins.model;
 
 public enum BuildResult {
-    FAILURE, UNSTABLE, REBUILDING, BUILDING, ABORTED, SUCCESS, UNKNOWN, NOT_BUILT, 
+    FAILURE, UNSTABLE, REBUILDING, BUILDING,
     /**
-     * This will be the result of a job in cases where it has been 
-     * cancelled during the time in the queue. 
+     * This means a job was already running and has been aborted.
+     */
+    ABORTED,
+    /**
+     * 
+     */
+    SUCCESS,
+    /**
+     * ?
+     */
+    UNKNOWN,
+    /**
+     * This is returned if a job has never been built.
+     */
+    NOT_BUILT,
+    /**
+     * This will be the result of a job in cases where it has been cancelled
+     * during the time in the queue.
      */
     CANCELLED
 }

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

@@ -25,6 +25,72 @@
  */
 public class BuildWithDetails extends Build {
 
+    /**
+     * This will be returned by the API in cases where the build has never run.
+     * For example {@link Build#BUILD_HAS_NEVER_RUN}
+     */
+    public static final BuildWithDetails BUILD_HAS_NEVER_RUN = new BuildWithDetails() {
+
+        @Override
+        public List getActions() {
+            return Collections.emptyList();
+        }
+
+        @Override
+        public List<Artifact> getArtifacts() {
+            return Collections.<Artifact>emptyList();
+        }
+
+        @Override
+        public List<BuildCause> getCauses() {
+            return Collections.<BuildCause>emptyList();
+        }
+
+        @Override
+        public List<BuildChangeSetAuthor> getCulprits() {
+            return Collections.<BuildChangeSetAuthor>emptyList();
+        }
+
+        @Override
+        public BuildResult getResult() {
+            return BuildResult.NOT_BUILT;
+        }
+
+    };
+
+    /**
+     * This will be returned by the API in cases where the build has been
+     * cancelled. For example {@link Build#BUILD_HAS_BEEN_CANCELLED}
+     */
+    public static final BuildWithDetails BUILD_HAS_BEEN_CANCELLED = new BuildWithDetails() {
+
+        @Override
+        public List getActions() {
+            return Collections.emptyList();
+        }
+
+        @Override
+        public List<Artifact> getArtifacts() {
+            return Collections.<Artifact>emptyList();
+        }
+
+        @Override
+        public List<BuildCause> getCauses() {
+            return Collections.<BuildCause>emptyList();
+        }
+
+        @Override
+        public List<BuildChangeSetAuthor> getCulprits() {
+            return Collections.<BuildChangeSetAuthor>emptyList();
+        }
+
+        @Override
+        public BuildResult getResult() {
+            return BuildResult.CANCELLED;
+        }
+
+    };
+
     private List actions; // TODO: Should be improved.
     private boolean building;
     private String description;
@@ -103,7 +169,9 @@ public boolean apply(Map<String, Object> action) {
     }
 
     /**
-     * Update <code>displayName</code> and the <code>description</code> of a build.
+     * Update <code>displayName</code> and the <code>description</code> of a
+     * build.
+     * 
      * @param displayName The new displayName which should be set.
      * @param description The description which should be set.
      * @param crumbFlag <code>true</code> or <code>false</code>.
@@ -113,14 +181,16 @@ public void updateDisplayNameAndDescription(String displayName, String descripti
             throws IOException {
         Objects.requireNonNull(displayName, "displayName is not allowed to be null.");
         Objects.requireNonNull(description, "description is not allowed to be null.");
-        //TODO: Check what the "core:apply" means?
+        // TODO: Check what the "core:apply" means?
         ImmutableMap<String, String> params = ImmutableMap.of("displayName", displayName, "description", description,
                 "core:apply", "", "Submit", "Save");
         client.post_form(this.getUrl() + "/configSubmit?", params, crumbFlag);
     }
 
     /**
-     * Update <code>displayName</code> and the <code>description</code> of a build.
+     * Update <code>displayName</code> and the <code>description</code> of a
+     * build.
+     * 
      * @param displayName The new displayName which should be set.
      * @param description The description which should be set.
      * @throws IOException in case of errors.
@@ -131,21 +201,23 @@ public void updateDisplayNameAndDescription(String displayName, String descripti
 
     /**
      * Update <code>displayName</code> of a build.
+     * 
      * @param displayName The new displayName which should be set.
      * @param crumbFlag <code>true</code> or <code>false</code>.
      * @throws IOException in case of errors.
      */
     public void updateDisplayName(String displayName, boolean crumbFlag) throws IOException {
         Objects.requireNonNull(displayName, "displayName is not allowed to be null.");
         String description = getDescription() == null ? "" : getDescription();
-        //TODO: Check what the "core:apply" means?
-        ImmutableMap<String, String> params = ImmutableMap.of("displayName", displayName, "description",
-                description, "core:apply", "", "Submit", "Save");
+        // TODO: Check what the "core:apply" means?
+        ImmutableMap<String, String> params = ImmutableMap.of("displayName", displayName, "description", description,
+                "core:apply", "", "Submit", "Save");
         client.post_form(this.getUrl() + "/configSubmit?", params, crumbFlag);
     }
 
     /**
      * Update <code>displayName</code> of a build.
+     * 
      * @param displayName The new displayName which should be set.
      * @throws IOException in case of errors.
      */
@@ -155,21 +227,23 @@ public void updateDisplayName(String displayName) throws IOException {
 
     /**
      * Update the <code>description</code> of a build.
+     * 
      * @param description The description which should be set.
      * @param crumbFlag <code>true</code> or <code>false</code>.
      * @throws IOException in case of errors.
      */
     public void updateDescription(String description, boolean crumbFlag) throws IOException {
         Objects.requireNonNull(description, "description is not allowed to be null.");
         String displayName = getDisplayName() == null ? "" : getDisplayName();
-        //TODO: Check what the "core:apply" means?
-        ImmutableMap<String, String> params = ImmutableMap.of("displayName", displayName, "description",
-                description, "core:apply", "", "Submit", "Save");
+        // TODO: Check what the "core:apply" means?
+        ImmutableMap<String, String> params = ImmutableMap.of("displayName", displayName, "description", description,
+                "core:apply", "", "Submit", "Save");
         client.post_form(this.getUrl() + "/configSubmit?", params, crumbFlag);
     }
 
     /**
      * Update the <code>description</code> of a build.
+     * 
      * @param description The description which should be set.
      * @throws IOException in case of errors.
      */
@@ -278,15 +352,15 @@ public boolean apply(Map<String, Object> action) {
     /**
      * @return The console output of the build. The line separation is done by
      *         {@code CR+LF}.
-     * @throws IOException
-     *             in case of a failure.
+     * @throws IOException in case of a failure.
      */
     public String getConsoleOutputText() throws IOException {
         return client.get(getUrl() + "/logText/progressiveText");
     }
 
     /**
      * The console output with HTML.
+     * 
      * @return The console output as HTML.
      * @throws IOException
      */