Basic Jenkins tasks and tests implemented

Author: Denis

README.md

@@ -1 +1,54 @@
-# pk-jenkins
+[![Release](https://jitpack.io/v/ProjectKaiser/pk-jenkins.svg)](https://jitpack.io/#ProjectKaiser/pk-jenkins)	
+
+# Overview
+Pk-jenkins is a tiny framework used to manage basic Jenkins tasks:
+- Jobs copy, create, read, update, delete
+- Run and read builds
+
+# Terms
+- Job
+  - Alias of Project in Jenkins terms
+- Job Detailed
+  - An user-level Job description: name, builds list etc 
+- Job Config Xml
+  - A Jenkins-level Job description: schtdule, used plugins config etc
+- Queue Item
+  - A build queue element. Represents a separate build for a task: color, state(running, finished, stuck etc) etc 
+  
+# Using pk-jenkins Api
+- Create IJenkinsApi implementation class providing Jenkins server url, username and password
+```java
+	IJenkinsApi jenkins = new JenkinsApi("http://localhost:8080", "user", "password");
+```
+- `void createJob(String jobName, String jobConfigXML)`
+  - Creates new job named `jobName` with provided job config xml. Use `getJobConfigXml()` to obtain one from an existing Job
+- `JobDetailed getJobDetailed(String jobName) throws EPKJNotFound`
+  - Returns Job Detailed object
+- `QueueItem getBuild(Long buildId) throws EPKJNotFound`
+  - Returns Queue item object
+- `void updateJobConfigXml(String jobName, String configXml) throws EPKJNotFound`
+  - Updates Job Config Xml. Xml manipulating is made by caller side, i.e.: `getJobConfigXml()`, then add\remove\change Xml elements, then `updateJobCOnfigXml()`
+- `void copyJob(String srcName, String dstName) throws EPKJNotFound, EPKJExists`
+  - Clones an existing Job
+- `List<String> getJobsList()`
+  - Returns list of all jobs on the server
+- `String getJobConfigXml(String jobName) throws EPKJNotFound`
+  - Returns Job Config Xml as a string
+- `void deleteJob(String jobName) throws EPKJNotFound`
+  - Deletes job
+  
+#Functional testing
+A working Jenkins server is required to run functional tests. 
+Also following environment vars or JVM vars must be defined: 
+- PK_TEST_JENKINS_URL
+  - URL to the Jenkins server used for tests
+- TEST_JENKINS_USER
+  - Jenkins username used for run tests
+- PK_TEST_JENKINS_PASS
+  - Password of Jenkins user used for run tests
+To run functional tests just execute JenkinsApiTest class as JUnit test. All jobs created during testing are deleted after automatically
+ 
+
+    
+
+

build.gradle

@@ -16,10 +16,13 @@ repositories {
 dependencies {
     testCompile 'junit:junit:4.12'
     testCompile 'org.mockito:mockito-core:2.0.62-beta'
+	testCompile 'xmlunit:xmlunit:1.6'
 
     compile 'commons-io:commons-io:2.4'
 	compile 'com.google.code.gson:gson:2.8.0'
 	compile 'org.apache.httpcomponents:httpclient:4.5.2'
+	compile 'commons-httpclient:commons-httpclient:3.1'
+	
 }
 
 task sourcesJar(type: Jar, dependsOn: classes) {

src/main/java/com/projectkaiser/scm/jenkins/api/IJenkinsApi.java

@@ -2,22 +2,29 @@
 
 import java.util.List;
 
+import com.projectkaiser.scm.jenkins.api.exceptions.EPKJExists;
+import com.projectkaiser.scm.jenkins.api.exceptions.EPKJNotFound;
 import com.projectkaiser.scm.jenkins.data.JobDetailed;
+import com.projectkaiser.scm.jenkins.data.QueueItem;
 
 public interface IJenkinsApi {
 
-	void createJob(String jobName, String jobConfigXML);
+	void createJob(String jobName, String jobConfigXML) throws EPKJExists;
 
-	JobDetailed getJobDetailed(String jobName);
+	JobDetailed getJobDetailed(String jobName) throws EPKJNotFound;
 
-	void runJob(String jobName);
+	Long enqueueBuild(String jobName) throws EPKJNotFound;
+	
+	QueueItem getBuild(Long buildId) throws EPKJNotFound;
 
-	void updateJobConfigXml(String jobName, String jobConfigXML);
+	void updateJobConfigXml(String jobName, String configXml) throws EPKJNotFound;
 
-	void copyJob(String srcName, String dstName);
+	void copyJob(String srcName, String dstName) throws EPKJNotFound, EPKJExists;
 
 	List<String> getJobsList();
 
-	String getJobConfigXml(String jobName);
+	String getJobConfigXml(String jobName) throws EPKJNotFound;
+	
+	void deleteJob(String jobName) throws EPKJNotFound;
 
 }

src/main/java/com/projectkaiser/scm/jenkins/api/JenkinsApi.java

@@ -8,18 +8,20 @@
 import java.util.List;
 import java.util.Map;
 
+import org.apache.http.Header;
+import org.apache.http.HttpResponse;
+
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.reflect.TypeToken;
+import com.projectkaiser.scm.jenkins.api.exceptions.EPKJExists;
+import com.projectkaiser.scm.jenkins.api.exceptions.EPKJNotFound;
+import com.projectkaiser.scm.jenkins.api.exceptions.EPKJenkinsException;
 import com.projectkaiser.scm.jenkins.api.facade.IJenkinsApiFacade;
 import com.projectkaiser.scm.jenkins.api.facade.JenkinsApiHttpFacade;
 import com.projectkaiser.scm.jenkins.data.JobDetailed;
-
-/*
-    http://localhost:8080/hudson/job/toolkit/api/json
-    http://gmpxp:8080/hudson/api/json?tree=jobs[name]
-    http://localhost:8080/hudson/job/toolkit-2/config.xml
-*/
+import com.projectkaiser.scm.jenkins.data.JobListElement;
+import com.projectkaiser.scm.jenkins.data.QueueItem;
 
 public class JenkinsApi implements IJenkinsApi {
 
@@ -30,13 +32,28 @@ public JenkinsApi(String baseAddress, String user, String password) {
 	}
 
 	@Override
-	public void runJob(String jobName) {
+	public Long enqueueBuild(String jobName) throws EPKJNotFound {
 		String url = "job/" + encodeUrl(jobName) + "/build";
-		facade.getResponsePOST(url, null);
+		HttpResponse resp = facade.getResponsePOST(url, null);
+		Header[] headers = resp.getHeaders("Location");
+		if (headers == null || headers.length == 0) {
+			throw new EPKJenkinsException("Failed to obtain Location header from response");
+		}
+		String[] strs = headers[0].getValue().split("/");
+		return Long.parseLong(strs[strs.length - 1]);
+	}
+	
+	@Override
+	public QueueItem getBuild(Long buildId) throws EPKJNotFound {
+		String url = String.format("queue/item/%d/api/json?pretty=true", buildId);
+		String queueItemJson = facade.getResponseContentGET(url);
+		Gson gson = new GsonBuilder().setPrettyPrinting().create();
+		QueueItem queueItem = gson.fromJson(queueItemJson, QueueItem.class);
+		return queueItem;
 	}
 
 	@Override
-	public void copyJob(String srcName, String dstName) {
+	public void copyJob(String srcName, String dstName) throws EPKJNotFound, EPKJExists {
 		String url = "createItem";
 		Map<String, String> q = new HashMap<String, String>();
 		q.put("name", dstName);
@@ -47,17 +64,17 @@ public void copyJob(String srcName, String dstName) {
 	}
 
 	@Override
-	public void createJob(String jobName, String jobConfigXML) {
+	public void createJob(String jobName, String jobConfigXML) throws EPKJExists {
 		String url = "createItem";
 		Map<String, String> q = new HashMap<String, String>();
 		q.put("name", jobName);
 		url = appendQuery(url, q);
-		facade.getResponsePOST(url, null);
+		facade.getResponsePOST(url, jobConfigXML);
 	}
 
 	private static String encodeUrl(String str) {
 		try {
-			return URLEncoder.encode(str, "UTF-8");
+			return URLEncoder.encode(str, "UTF-8").replace("+", "%20");
 		} catch (UnsupportedEncodingException e) {
 			throw new RuntimeException(e);
 		}
@@ -81,33 +98,46 @@ public List<String> getJobsList() {
 		Map<String, String> q = new HashMap<String, String>();
 		q.put("tree", "jobs[name]");
 		url = appendQuery(url, q);
-		String json = facade.getResponseGET(url);
+		String json = facade.getResponseContentGET(url);
 		Gson gson = new GsonBuilder().create();
-		Type type = new TypeToken<Map<String, Map<String, String>>>() {
+		Type type = new TypeToken<Map<String, List<JobListElement>>>() {
 		}.getType();
 
-		Map<String, Map<String, String>> res = gson.fromJson(json, type);
-		return new ArrayList(res.get("jobs").values());
+		Map<String, List<JobListElement>> jobsMap = gson.fromJson(json, type);
+		List<JobListElement> jobs = jobsMap.get("jobs");
+		List<String> res = new ArrayList<>();
+		for (JobListElement job : jobs) {
+			res.add(job.getName());
+		}
+		return res;
 	}
 
 	@Override
-	public String getJobConfigXml(String jobName) {
+	public String getJobConfigXml(String jobName) throws EPKJNotFound {
 		String url = "job/" + encodeUrl(jobName) + "/config.xml";
-		return facade.getResponseGET(url);
+		return facade.getResponseContentGET(url);
 	}
 
 	@Override
-	public void updateJobConfigXml(String jobName, String jobConfigXML) {
+	public void updateJobConfigXml(String jobName, String configXml) throws EPKJNotFound {
 		String url = "job/" + encodeUrl(jobName) + "/config.xml";
-		facade.getResponsePOST(url, jobConfigXML);
+		facade.getResponsePOST(url, configXml);
 	}
 
 	@Override
-	public JobDetailed getJobDetailed(String jobName) {
+	public JobDetailed getJobDetailed(String jobName) throws EPKJNotFound {
 		String url = "job/" + encodeUrl(jobName) + "/api/json?pretty=true";
-		String json = facade.getResponseGET(url);
+		String json = facade.getResponseContentGET(url);
 		Gson gson = new GsonBuilder().setPrettyPrinting().create();
 		JobDetailed job = gson.fromJson(json, JobDetailed.class);
 		return job;
 	}
+
+	@Override
+	public void deleteJob(String jobName) throws EPKJNotFound {
+		String url = "job/" + encodeUrl(jobName) + "/doDelete";
+		facade.getResponsePOST(url, null);
+	}
+
+	
 }

src/main/java/com/projectkaiser/scm/jenkins/api/exceptions/EPKJExists.java

@@ -0,0 +1,11 @@
+package com.projectkaiser.scm.jenkins.api.exceptions;
+
+public class EPKJExists extends EPKJenkinsServerException {
+
+	public EPKJExists(Integer code, String errorMessage) {
+		super(code, errorMessage);
+	}
+
+	private static final long serialVersionUID = 7637144484632267911L;
+
+}

src/main/java/com/projectkaiser/scm/jenkins/api/exceptions/EPKJNotFound.java

@@ -0,0 +1,11 @@
+package com.projectkaiser.scm.jenkins.api.exceptions;
+
+public class EPKJNotFound extends EPKJenkinsServerException {
+
+	public EPKJNotFound(Integer code, String errorMes) {
+		super(code, errorMes);
+	}
+
+	private static final long serialVersionUID = 2478559349028227084L;
+
+}

src/main/java/com/projectkaiser/scm/jenkins/api/exceptions/EPKJenkinsException.java

@@ -0,0 +1,11 @@
+package com.projectkaiser.scm.jenkins.api.exceptions;
+
+public class EPKJenkinsException extends RuntimeException {
+
+	public EPKJenkinsException(String string) {
+		super(string);
+	}
+
+	private static final long serialVersionUID = 5415122631779829397L;
+
+}

src/main/java/com/projectkaiser/scm/jenkins/api/exceptions/EPKJenkinsServerException.java

@@ -0,0 +1,29 @@
+package com.projectkaiser.scm.jenkins.api.exceptions;
+
+import org.apache.commons.httpclient.HttpStatus;
+
+public class EPKJenkinsServerException extends EPKJenkinsException {
+
+	private static final long serialVersionUID = 8612747334003389372L;
+	private String errorMessage;
+	private Integer code;
+
+	public String getErrorMessage() {
+		return errorMessage;
+	}
+
+	public Integer getCode() {
+		return code;
+	}
+
+	public EPKJenkinsServerException(Integer code, String errorMessage) {
+		super(HttpStatus.getStatusText(code));
+		this.code = code;
+		this.errorMessage = errorMessage;
+	}
+	
+	@Override
+	public String toString() {
+		return String.format("%s (%d: %s)", errorMessage, code, super.getMessage());
+	}
+}

src/main/java/com/projectkaiser/scm/jenkins/api/facade/IJenkinsApiFacade.java

@@ -1,7 +1,11 @@
 package com.projectkaiser.scm.jenkins.api.facade;
 
+import org.apache.http.HttpResponse;
+
 public interface IJenkinsApiFacade {
-	String getResponseGET(String url);
+	HttpResponse getResponseGET(String url);
+	
+	String getResponseContentGET(String url);
 
-	String getResponsePOST(String url, String entity);
+	HttpResponse getResponsePOST(String url, String entity);
 }