add comments

.gitignore

@@ -23,3 +23,4 @@ hs_err_pid*
 .gradle
 out/
 build/
+gradle.properties

build.gradle

@@ -1,9 +1,22 @@
+buildscript {
+    repositories {
+        jcenter()
+    }
+    dependencies {
+        classpath 'com.bmuschko:gradle-nexus-plugin:2.3.1'
+    }
+}
+
+
 plugins {
     id 'java'
+    id 'maven-publish'
+    id 'io.codearte.nexus-staging' version '0.11.0'
 }
+apply plugin: 'com.bmuschko.nexus'
 
-group 'org.k1'
-version '0.1-SNAPSHOT'
+group 'io.github.kev1nst'
+version '1.0.1'
 
 sourceCompatibility = 1.8
 
@@ -15,3 +28,46 @@ dependencies {
     compile group: 'org.nutz', name: 'nutz', version: '1.r.67'
     testCompile group: 'junit', name: 'junit', version: '4.12'
 }
+
+nexusStaging {
+
+}
+
+modifyPom {
+    project {
+        name = 'Jenkins Client'
+        description = 'Light-weight Jenkins REST API Client for Java'
+        url = 'https://github.com/kev1nst/jenkins-rest'
+        licenses {
+            license {
+                name = 'The Apache License, Version 2.0'
+                url = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
+            }
+        }
+        developers {
+            developer {
+                id = 'kev1nst'
+                name = 'Tianshuo Zhao'
+                email = 'zts116@gmail.com'
+            }
+        }
+        scm {
+            connection = 'scm:git:git://github.com/kev1nst/jenkins-rest.git'
+            developerConnection = 'scm:git:ssh://github.com/kev1nst/jenkins-rest.git'
+            url = 'https://github.com/kev1nst/jenkins-rest'
+        }
+    }
+}
+
+extraArchive {
+    sources = true
+    tests = true
+    javadoc = true
+}
+
+nexus {
+    sign = true
+    repositoryUrl = 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
+    snapshotRepositoryUrl = 'https://oss.sonatype.org/content/repositories/snapshots/'
+}
+

settings.gradle

@@ -1,2 +1,2 @@
-rootProject.name = 'jenclight'
+rootProject.name = 'jenkins-rest'
 

src/main/java/io/github/kev1nst/jenkins/Jenkins.java

@@ -12,8 +12,9 @@
 import org.nutz.json.Json;
 import org.nutz.log.Log;
 import org.nutz.log.Logs;
-import sun.misc.BASE64Encoder;
 
+import java.io.UnsupportedEncodingException;
+import java.util.Base64;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -22,10 +23,11 @@
 /**
  * Light-weight Jenkins client for Java, based on Jenkins REST API
  * @author kevinzhao
- * @date 20/07/2019
+ * @since 20/07/2019
  */
 public class Jenkins {
 
+    private static final String UTF_8 = "utf-8";
     private String url;
     private Header header;
     private int timeout = 10000;
@@ -36,15 +38,21 @@ private Jenkins(String url, String account, String creds) {
 
     /**
      * re-authenticate the jenkins instance if the crumb is expired
-     * @param url
-     * @param account
-     * @param creds
-     * @return
+     * @param url the jenkins url
+     * @param account the jenkins account username
+     * @param creds the jenkins account password or api token
+     * @return Jenkins obj
      */
     public Jenkins auth(String url, String account, String creds) {
         this.url = url;
         Header header = Header.create();
-        String auth = new BASE64Encoder().encode(String.format("%s:%s", account, creds).getBytes());
+
+        String auth = null;
+        try {
+            auth = new String(Base64.getEncoder().encode(String.format("%s:%s", account, creds).getBytes(UTF_8)),UTF_8);
+        } catch (UnsupportedEncodingException e) {
+            throw new JenkinsException(e);
+        }
         header.addv(Constant.AUTHORIZATION, "Basic " + auth);
         Response res = Http.get(String.format(Constant.ISSUER_API_JSON, url), header, timeout);
         if (!res.isOK()) {
@@ -59,10 +67,10 @@ public Jenkins auth(String url, String account, String creds) {
 
     /**
      * static constructor of Jenkins class
-     * @param url
-     * @param account
-     * @param creds
-     * @return
+     * @param url the jenkins url
+     * @param account the jenkins account username
+     * @param creds the jenkins account password or api token
+     * @return the jenkins obj
      */
     public static Jenkins connect(String url, String account, String creds) {
         return new Jenkins(url, account, creds);
@@ -71,8 +79,8 @@ public static Jenkins connect(String url, String account, String creds) {
     /**
      * build jenkins job with parameter
      * @param jobPath full job path of jenkins job
-     * @param params  job parameter map
-     * @return
+     * @param params  job parameter map, the key/value pair in this map should match the jenkins parameter key/value pair
+     * @return the jenkins obj
      */
     public JobBuilder build(String jobPath, Map<String, Object> params) {
         String jobUrl;
@@ -96,7 +104,7 @@ public JobBuilder build(String jobPath, Map<String, Object> params) {
     /**
      * build jenkins job without parameter
      * @param jobPath full job path of jenkins job
-     * @return
+     * @return the job builder obj, it allows synchronized job result waiting through await method
      */
     public JobBuilder build(String jobPath) {
         return build(jobPath, null);

src/main/java/io/github/kev1nst/jenkins/job/JobBuilder.java

@@ -48,17 +48,24 @@ public BuildStatus await(int timeout, JobProgressHandler jobProgressHandler) {
 
     /**
      * @param timeout in ms
-     * @return
+     * @return the build status obj
      */
     public BuildStatus await(int timeout) {
         JobProgressHandler jobProgressHandler = new DefaultJobProgressHandler(LOG);
         return await(timeout, jobProgressHandler);
     }
-
+    /**
+     * @return the build status obj
+     */
     public BuildStatus await() {
         return await(JOB_TIMEOUT);
     }
 
+    /**
+     *
+     * @param jobProgressHandler define job event handler including job log
+     * @return the build status obj
+     */
     public BuildStatus await(JobProgressHandler jobProgressHandler) {
         return await(JOB_TIMEOUT, jobProgressHandler);
     }

src/main/java/io/github/kev1nst/jenkins/job/handler/JobProgressHandler.java

@@ -20,13 +20,14 @@ public interface JobProgressHandler {
 
     /**
      * trigger after job start to execute
-     * @param item
+     * @param item queueItem of jenkins job, from which you can get the executable detail
      */
     void onExecute(QueueItem item);
 
     /**
      * trigger after job complete
-     * @param status
+     * @param status the build status of jenkins job
+     *              from which you can get the complete status and other attrs
      */
     void onCompleted(BuildStatus status);
 }

src/main/java/io/github/kev1nst/jenkins/job/handler/impl/DefaultJobProgressHandler.java

@@ -16,7 +16,7 @@ public class DefaultJobProgressHandler implements JobProgressHandler {
 
     @Override
     public void onExecute(QueueItem item) {
-        System.out.println(item);
+
     }
 
     public DefaultJobProgressHandler(Log LOG) {
@@ -30,12 +30,12 @@ public void log(String logEntry, int index) {
 
     @Override
     public void onSubmit(JobSubmission jobSubmission) {
-        System.out.println(jobSubmission);
+
     }
 
     @Override
     public void onCompleted(BuildStatus buildStatus) {
-        System.out.println(buildStatus);
+
     }
 
 }

src/test/java/io/github/kev1nst/jenkins/Demo.java

@@ -13,42 +13,35 @@
  */
 
 public class Demo {
+
+    private static final String CREDENTIAL = "9aebe96f61819ce2c20c01a820719f70"; // could be password or api token
+    private static final String ACCOUNT = "admin";
+    private static final String JENKINS_URL = "http://localhost:8081";
+
     @Test
     public void simpleBuild() {
-        String jenkinsUrl = "http://localhost:8081";
-        String account = "admin";
-        String credential = "9aebe96f61819ce2c20c01a820719f70"; // could be token or password
-        Jenkins jenkins = Jenkins.connect(jenkinsUrl, account, credential);
+        Jenkins jenkins = Jenkins.connect(JENKINS_URL, ACCOUNT, CREDENTIAL);
         BuildStatus result = jenkins.build("pack1/job1").await(); // await method is synchronized call
         assert result.isSuccess();
     }
 
     @Test
     public void buildWithParameter() {
-        String jenkinsUrl = "http://localhost:8081";
-        String account = "admin";
-        String credential = "9aebe96f61819ce2c20c01a820719f70"; // could be token or password
-        Jenkins jenkins = Jenkins.connect(jenkinsUrl, account, credential);
+       Jenkins jenkins = Jenkins.connect(JENKINS_URL, ACCOUNT, CREDENTIAL);
         BuildStatus result = jenkins.build("pack1/job2", Lang.map("param1", "param_value")).await();
         assert result.isSuccess();
     }
 
     @Test
     public void buildWithTimeout() {
-        String jenkinsUrl = "http://localhost:8081";
-        String account = "admin";
-        String credential = "9aebe96f61819ce2c20c01a820719f70"; // could be token or password
-        Jenkins jenkins = Jenkins.connect(jenkinsUrl, account, credential);
+        Jenkins jenkins = Jenkins.connect(JENKINS_URL, ACCOUNT, CREDENTIAL);
         BuildStatus result = jenkins.build("pack1/job2", Lang.map("param1", "param_value")).await(100000);
         assert result.isSuccess();
     }
 
     @Test
     public void buildWithProgressHandler() {
-        String jenkinsUrl = "http://localhost:8081";
-        String account = "admin";
-        String credential = "9aebe96f61819ce2c20c01a820719f70"; // could be token or password
-        Jenkins jenkins = Jenkins.connect(jenkinsUrl, account, credential);
+        Jenkins jenkins = Jenkins.connect(JENKINS_URL, ACCOUNT, CREDENTIAL);
         BuildStatus result = jenkins.build("pack1/job2", Lang.map("param1", "param_value")).await(new JobProgressHandler() {
             @Override