Return model instead of just number when triggering a build

Author: aliok

README.md

@@ -11,10 +11,18 @@ Create job:
   client.createJob("java-client-job1","https://github.com/wtrocki/helloworld-android-gradle","master");
 ```
 
+Trigger a job:
+
+```
+  ...
+  BuildStatus buildStatus = client.build("java-client-job1");
+```
+
 ## Requirements
 
 Client works with Java6 and above.
 
 ## Building
 
-`mvn clean package`
+`mvn clean package`
+

pom.xml

@@ -18,6 +18,7 @@
     </licenses>
 
     <dependencies>
+      <!--Compile time-->
         <dependency>
             <groupId>com.offbytwo.jenkins</groupId>
             <artifactId>jenkins-client</artifactId>
@@ -38,13 +39,35 @@
         <artifactId>slf4j-log4j12</artifactId>
         <version>1.7.21</version>
       </dependency>
+
+      <!--Testing-->
+      <dependency>
+        <groupId>junit</groupId>
+        <artifactId>junit</artifactId>
+        <version>4.12</version>
+        <scope>test</scope>
+      </dependency>
+
+      <dependency>
+        <groupId>org.mockito</groupId>
+        <artifactId>mockito-core</artifactId>
+        <version>1.10.19</version>
+        <scope>test</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.assertj</groupId>
+        <artifactId>assertj-core</artifactId>
+        <version>3.6.1</version>
+        <scope>test</scope>
+      </dependency>
     </dependencies>
     <repositories>
         <repository>
             <id>jcenter</id>
             <url>https://jcenter.bintray.com/</url>
         </repository>
     </repositories>
+
     <build>
         <plugins>
             <plugin>
@@ -56,6 +79,11 @@
                     <target>1.6</target>
                 </configuration>
             </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <version>2.12.4</version>
+          </plugin>
         </plugins>
     </build>
 </project>

src/main/java/com/redhat/digkins/DiggerClient.java

@@ -1,6 +1,7 @@
 package com.redhat.digkins;
 
 import com.offbytwo.jenkins.JenkinsServer;
+import com.redhat.digkins.model.BuildStatus;
 import com.redhat.digkins.services.CreateJobService;
 import com.redhat.digkins.services.TriggerBuildService;
 import com.redhat.digkins.util.DiggerClientException;
@@ -69,27 +70,32 @@ public void createJob(String name, String gitRepo, String gitBranch) throws Digg
    * it and a build number is assigned to the build.
    * <p>
    * This method will block until there is a build number, or the given timeout period is passed. If the build is still in the queue
-   * after the given timeout period, -1 is returned as the build number.
+   * after the given timeout period, a {@code BuildStatus} is returned with state {@link BuildStatus.State#TIMED_OUT}.
    * <p>
    * Please note that timeout period is never meant to be very precise. It has the resolution of {@link TriggerBuildService#POLL_PERIOD} because
    * timeout is checked before every pull.
    * <p>
-   * Similarly, -1 is returned if the build is stuck or cancelled on Jenkins side.
+   * Similarly, {@link BuildStatus.State#CANCELLED_IN_QUEUE} is returned if the build is cancelled on Jenkins side and
+   * {@link BuildStatus.State#STUCK_IN_QUEUE} is returned if the build is stuck.
    *
    * @param jobName name of the job to trigger the build
-   * @param timeout how many milliseconds should this call block before returning -1. Should be larger than {@link TriggerBuildService#FIRST_CHECK_DELAY}
-   * @return the build number. -1 if build is cancelled, stuck or in queue more than the given timeout period
+   * @param timeout how many milliseconds should this call block before returning {@link BuildStatus.State#TIMED_OUT}.
+   *                Should be larger than {@link TriggerBuildService#FIRST_CHECK_DELAY}
+   * @return the build status
    * @throws DiggerClientException if connection problems occur during connecting to Jenkins
    */
-  public long build(String jobName, long timeout) throws DiggerClientException {
+  public BuildStatus build(String jobName, long timeout) throws DiggerClientException {
     final TriggerBuildService triggerBuildService = new TriggerBuildService(jenkins);
     try {
       return triggerBuildService.build(jobName, timeout);
     } catch (IOException e) {
       LOG.debug("Exception while connecting to Jenkins", e);
       throw new DiggerClientException(e);
     } catch (InterruptedException e) {
-      LOG.debug("Exception while sleeping between checks", e);
+      LOG.debug("Exception while waiting on Jenkins", e);
+      throw new DiggerClientException(e);
+    } catch (Throwable e) {
+      LOG.debug("Exception while triggering a build", e);
       throw new DiggerClientException(e);
     }
   }
@@ -100,11 +106,11 @@ public long build(String jobName, long timeout) throws DiggerClientException {
    * Calls {@link #build(String, long)} with a default timeout of {@link #DEFAULT_BUILD_TIMEOUT}.
    *
    * @param jobName name of the job
-   * @return the build number
+   * @return the build status
    * @throws DiggerClientException if connection problems occur during connecting to Jenkins
    * @see #build(String, long)
    */
-  public long build(String jobName) throws DiggerClientException {
+  public BuildStatus build(String jobName) throws DiggerClientException {
     return this.build(jobName, DEFAULT_BUILD_TIMEOUT);
   }
 

src/main/java/com/redhat/digkins/model/BuildStatus.java

@@ -0,0 +1,67 @@
+package com.redhat.digkins.model;
+
+/**
+ * Represents the status of a build.
+ * <p>
+ * The field {@link #buildNumber} will only be set if the
+ * {@link #state} is {@link State#BUILDING}.
+ **/
+public class BuildStatus {
+
+  public enum State {
+    /**
+     * Build is out of the queue and it is currently being executed.
+     */
+    BUILDING,
+
+    /**
+     * The max time to wait for the build get executed has passed.
+     * This state doesn't have to mean build is stuck or etc.
+     * It just means, the max waiting time has passed on the client side.
+     */
+    TIMED_OUT,
+
+    /**
+     * The build is cancelled in Jenkins before it started being executed.
+     */
+    CANCELLED_IN_QUEUE,
+
+    /**
+     * The build is stuck on Jenkins queue.
+     */
+    STUCK_IN_QUEUE
+  }
+
+  private final State state;
+  private final int buildNumber;
+
+  public BuildStatus(State state, int buildNumber) {
+    this.state = state;
+    this.buildNumber = buildNumber;
+  }
+
+  /**
+   * @return state of the build
+   */
+  public State getState() {
+    return state;
+  }
+
+  /**
+   * This should only be valid if the
+   * {@link #state} is {@link State#BUILDING}.
+   *
+   * @return the build number assigned by Jenkins
+   */
+  public int getBuildNumber() {
+    return buildNumber;
+  }
+
+  @Override
+  public String toString() {
+    return "BuildStatus{" +
+      "state=" + state +
+      ", buildNumber=" + buildNumber +
+      '}';
+  }
+}

src/main/java/com/redhat/digkins/services/TriggerBuildService.java

@@ -5,6 +5,7 @@
 import com.offbytwo.jenkins.model.JobWithDetails;
 import com.offbytwo.jenkins.model.QueueItem;
 import com.offbytwo.jenkins.model.QueueReference;
+import com.redhat.digkins.model.BuildStatus;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -28,39 +29,41 @@ public class TriggerBuildService {
   public static final long POLL_PERIOD = 2 * 1000L;
 
 
-  private JenkinsServer jenkins;
+  private JenkinsServer jenkinsServer;
 
   /**
-   * @param jenkins jenkins api instance
+   * @param jenkinsServer jenkins api instance
    */
-  public TriggerBuildService(JenkinsServer jenkins) {
-    this.jenkins = jenkins;
+  public TriggerBuildService(JenkinsServer jenkinsServer) {
+    this.jenkinsServer = jenkinsServer;
   }
 
   /**
    * See the documentation in {@link com.redhat.digkins.DiggerClient#build(String, long)}
    *
    * @param jobName name of the job
    * @param timeout timeout
-   * @return the build number
+   * @return the build status
    * @throws IOException          if connection problems occur during connecting to Jenkins
    * @throws InterruptedException if a problem occurs during sleeping between checks
    * @see com.redhat.digkins.DiggerClient#build(String, long)
    */
-  public long build(String jobName, long timeout) throws IOException, InterruptedException {
-    final long timeoutTime = System.currentTimeMillis() + timeout;
+  public BuildStatus build(String jobName, long timeout) throws IOException, InterruptedException {
+    final long whenToTimeout = System.currentTimeMillis() + timeout;
 
     LOG.debug("Going to build job with name: {}", jobName);
     LOG.debug("Going to timeout in {} msecs if build didn't start executing", timeout);
 
-    JobWithDetails job = jenkins.getJob(jobName);
+    JobWithDetails job = jenkinsServer.getJob(jobName);
     if (job == null) {
+      LOG.debug("Unable to find job for name '{}'", jobName);
       throw new IllegalArgumentException("Unable to find job for name '" + jobName + "'");
     }
 
     final QueueReference queueReference = job.build();
     if (queueReference == null) {
       // this is probably an implementation problem we have here
+      LOG.debug("Queue reference cannot be null!");
       throw new IllegalStateException("Queue reference cannot be null!");
     }
     LOG.debug("Build triggered; queue item reference: {}", queueReference.getQueueItemUrlPart());
@@ -74,22 +77,23 @@ public long build(String jobName, long timeout) throws IOException, InterruptedE
 
     QueueItem queueItem;
     while (true) {
-      queueItem = jenkins.getQueueItem(queueReference);
+      queueItem = jenkinsServer.getQueueItem(queueReference);
       LOG.debug("Queue item : {}", queueItem);
 
       if (queueItem == null) {
         // this is probably an implementation problem we have here
+        LOG.debug("Queue item cannot be null!");
         throw new IllegalStateException("Queue item cannot be null!");
       }
 
       LOG.debug("Build item cancelled:{}, blocked:{}, buildable:{}, stuck:{}", queueItem.isCancelled(), queueItem.isBlocked(), queueItem.isBuildable(), queueItem.isStuck());
 
       if (queueItem.isCancelled()) {
-        LOG.debug("Queue item is cancelled. Returning -1");
-        return -1;
+        LOG.debug("Queue item is cancelled. Returning CANCELLED_IN_QUEUE");
+        return new BuildStatus(BuildStatus.State.CANCELLED_IN_QUEUE, -1);
       } else if (queueItem.isStuck()) {
-        LOG.debug("Queue item is stuck. Returning -1");
-        return -1;
+        LOG.debug("Queue item is stuck. Returning STUCK_IN_QUEUE");
+        return new BuildStatus(BuildStatus.State.STUCK_IN_QUEUE, -1);
       }
 
       // do not return -1 if blocked.
@@ -99,15 +103,15 @@ public long build(String jobName, long timeout) throws IOException, InterruptedE
 
       if (executable != null) {
         LOG.debug("Build has an executable. Returning build number: {}", executable.getNumber());
-        return executable.getNumber();
+        return new BuildStatus(BuildStatus.State.BUILDING, executable.getNumber().intValue());
       } else {
         LOG.debug("Build did not start executing yet.");
-        if (timeoutTime < System.currentTimeMillis()) {
+        if (whenToTimeout > System.currentTimeMillis()) {
           LOG.debug("Timeout period has not exceeded yet. Sleeping for {} msecs", POLL_PERIOD);
           Thread.sleep(POLL_PERIOD);
         } else {
-          LOG.debug("Timeout period has exceeded. Returning -1.");
-          return -1;
+          LOG.debug("Timeout period has exceeded. Returning TIMED_OUT.");
+          return new BuildStatus(BuildStatus.State.TIMED_OUT, -1);
         }
       }
 

src/main/resources/log4j.xml

@@ -11,7 +11,7 @@
     </appender>
 
     <logger name="com.redhat.digkins">
-        <level value="DEBUG"/>
+        <level value="INFO"/>
     </logger>
 
     <root>