Remote access API et Hudson

Hudson est un serveur d’intégration continue très riche. Parmi ses fonctionnalités, il expose l’ensemble des opérions de l’utilisateur par API. Dans un style REST, l’utilisateur va ainsi très facilement pouvoir réaliser les opérations CRUD sur un projet Hudson (nommée job Hudson), déclencher un build ou même récupérer le résultat des différents builds. Ce mécanisme est très puissant mais souvent inexploité par les utilisateurs de Hudson.

Pour connaître les opérations disponibles, il vous suffit de rajouter le path ‘api’ à votre URL Hudson dans le contexte courant comme

• http://localhost:8090/hudson/api/
• http://localhost:80980/hudson/job/test-gradle/api/
• http://localhost:8090/hudson/job/test-gradle/17/api/

Ci-dessous une suite d’exemple d’interactions, avec une implémentation Java basée sur la librairie Jakarta Commons HttpClient.

Pour s’authentifier

Utilisation de la ressource “hudsonBaseURL/j_acegi_security_check”

1. private HttpClient authenticate(String hudsonBaseURL) throws IOException, HttpException {
2. HttpClient client = new HttpClient();
3. PostMethod postMethodAuth = new PostMethod(hudsonBaseURL + “/j_acegi_security_check”);
4. NameValuePair[] postData = new NameValuePair[3];
5. postData[0] = new NameValuePair(“j_username”, “gboissinot”);
6. postData[1] = new NameValuePair(“j_password”, “zenika”);
7. postData[2] = new NameValuePair(“Login”, “login”);
8. postMethodAuth.addParameters(postData);
9. try {
10. int status= client.executeMethod(postMethodAuth);
11. System.out.println(status + “n“+ postMethodAuth.getResponseBodyAsString());
12. } finally {
13. postMethodAuth.releaseConnection();
14. }
15. return client;
16. }

Pour valider une URL Hudson

Vérification de la présence de l’entête HTTP “X-Hudson”

1. private boolean isHudsonURL (String hudsonBaseURL) throws IOException, HttpException {
2. HttpClient client= new HttpClient();
3. GetMethod getMethod = new GetMethod(hudsonBaseURL);
4. boolean isHudsonURL=false;
5. try {
6. int status = client.executeMethod(getMethod);
7. System.out.println(status + “n“+ getMethod.getResponseBodyAsString());
8. isHudsonURL=getMethod.getResponseHeader(“X-Hudson”)!=null;
9. } finally {
10. getMethod.releaseConnection();
11. }
12. return isHudsonURL;
13. }

Pour créer un job Hudson

Envoie du fichier de configuration du job config.xml à la ressource hudsonBaseURL/createItem avec le paramètre name=jobName

1. private void put(HttpClient client, String hudsonBaseURL,String jobName, File configFile) throws IOException, HttpException {
2. PostMethod postMethod = new PostMethod(hudsonBaseURL+ “/createItem?name=” + jobName);
3. postMethod.setRequestHeader(“Content-type”,“application/xml; charset=ISO-8859-1”);
4. postMethod.setRequestBody(new FileInputStream(configFile));
5. postMethod.setDoAuthentication(true);
6. try {
7. int status = client.executeMethod(postMethod);
8. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
9. } finally {
10. postMethod.releaseConnection();
11. }
12. }

Pour mettre à jour un job Hudson

Envoie à la ressource hudsonBaseURL/job/jobName/config.xml d’un nouveau fichier de configuration config.xml

1. private void update(HttpClient client, String hudsonBaseURL,String jobName, File updateFile) throws IOException, HttpException {
2. PostMethod postMethod = new PostMethod(hudsonBaseURL + “/job/”+ jobName + “/config.xml”);
3. postMethod.setRequestHeader(“Content-type”,“text/xml; charset=ISO-8859-1”);
4. postMethod.setRequestBody(new FileInputStream(updateFile));
5. try {
6. int status = client.executeMethod(postMethod);
7. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
8. } finally {
9. postMethod.releaseConnection();
10. }
11. }

Pour copier un job Hudson

Envoie d’une requête POST à la ressource hudsonBaseURL/createItem avec 3 paramètres name=newJobName, mode=copy et from=originJobName

1. private void copy(HttpClient client, String hudsonBaseURL,String originJobName, String newJobName) throws IOException, HttpException {
2. PostMethod postMethod = new PostMethod(hudsonBaseURL + “/createItem”);
3. NameValuePair n1 = new NameValuePair(“name”, newJobName);
4. NameValuePair n2 = new NameValuePair(“mode”, “copy”);
5. NameValuePair n3 = new NameValuePair(“from”, originJobName);
6. postMethod.setQueryString(new NameValuePair[] { n1, n2, n3 });
7. postMethod.setRequestHeader(“Content-type”,“text/plain; charset=ISO-8859-1”);
8. try {
9. int status = client.executeMethod(postMethod);
10. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
11. } finally {
12. postMethod.releaseConnection();
13. }
14. }

Pour supprimer un job Hudson

Envoie d’une requête POST à la ressource hudsonBaseURL/job/jobName/doDelete

1. private void delete(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
2. PostMethod postMethod = new PostMethod(hudsonBaseURL + “/job/”+ jobName + “/doDelete”);
3. try {
4. int status = client.executeMethod(postMethod);
5. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
6. } finally {
7. postMethod.releaseConnection();
8. }
9. }

Pour activer et désactiver un job Hudson

Envoie de requêtes POST aux ressources hudsonBaseURL/job/jobName/enable et hudsonBaseURL/job/jobName/disable

1. private void enable(HttpClien t client, String hudsonBaseURL,String jobName) throws IOException, HttpException {
2. PostMethod postMethod = new PostMethod(hudsonBaseURL + “/job/”+ jobName + “/enable”);
3. try {
4. int status = client.executeMethod(postMethod);
5. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
6. } finally {
7. postMethod.releaseConnection();
8. }
9. }
11. private void disable(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
12. PostMethod postMethod = new PostMethod(hudsonBaseURL + “/job/”+ jobName + “/disable”);
13. try {
14. int status = client.executeMethod(postMethod);
15. System.out.println(status + “n“+ postMethod.getResponseBodyAsString());
16. } finally {
17. postMethod.releaseConnection();
18. }
19. }

Pour récupérer le fichier de configuration config.xml d’un job Hudson

Récupérer la réponse d’une requête à la ressource hudsonBaseURL/job/jobName/config.xml

1. private void fetch(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
2. GetMethod getMethod = new GetMethod(hudsonBaseURL + “/job/” + jobName+ “/config.xml”);
3. try {
4. int returnCode = client.executeMethod(getMethod);
5. System.out.print(returnCode);
6. byte[] response = getMethod.getResponseBody();
7. System.out.println(new String(response));
8. } finally {
9. getMethod.releaseConnection();
10. }
11. }

Pour lancer le build d’un job

Invoquer la ressource hudsonBaseURL/job/jobName/build

1. private void launchBuild(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
2. GetMethod getMethod = new GetMethod(hudsonBaseURL + “/job/”+ jobName+ “/build”);
3. try {
4. int status = client.executeMethod(getMethod);
5. System.out.println(status + “n“+ getMethod.getResponseBodyAsString());
6. } finally {
7. getMethod.releaseConnection();
8. }
9. }

Pour lancer le build d’un job avec des paramètres

Invoquer la ressource hudsonBaseURL/job/jobName/buildWithParameters avec les paramètres du job

1. private void launchBuildWithParameters(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
2. GetMethod getMethod = new GetMethod(hudsonBaseURL + “/job/”+ jobName+ “/buildWithParameters?param1=value1”);
3. try {
4. int status = client.executeMethod(getMethod);
5. System.out.println(status + “n“+ getMethod.getResponseBodyAsString());
6. } finally {
7. getMethod.releaseConnection();
8. }
9. }

Pour récupérer la date du dernier succès d’un job

Invoquer la ressource hudsonBaseURL/job/jobName/lastSuccessfulBuild/buildTimestamp avec le paramètre format contenant comme valeur le pattern de la date désiré selon l’API SimpleDateFormat

1. private void lastSuccessfulBuild(HttpClient client, String hudsonBaseURL, String jobName) throws IOException, HttpException {
2. GetMethod getMethod = new GetMethod(hudsonBaseURL + “/job/”+ jobName+ “/lastSuccessfulBuild/buildTimestamp?format=dd/MM/yyyy”);
3. try {
4. int status = client.executeMethod(getMethod);
5. System.out.println(status + “n“+ getMethod.getResponseBodyAsString());
6. } finally {
7. getMethod.releaseConnection();
8. }
9. }

Pour récupérer le status de l’ensemble des jobs d’un dashboard Hudson

Invoquer la ressource hudsonBaseURL/api/xml et traiter le résultat

1. private void read(String hudsonBaseURL) throws IOException, HttpException,DocumentException {
2. URL url = new URL(hudsonBaseURL + “/api/xml”);
3. Document dom = new SAXReader().read(url);
4. for (Element job : (List<Element>) dom.getRootElement().elements(“job”)) {
5. System.out.println(String.format(“Name:%stStatus:%s”, job.elementText(“name”), job.elementText(“color”)));
6. }
7. }

La capacité de piloter Hudson par API est très utile dans de nombreuses situations, comme dans la création d’un installateur de projets démonstrateurs ou d’un système d’orchestration qui piloterait un ensemble de jobs Hudson.
Pour avoir plus d’informations sur cette fonctionnalité, veuillez consulter la section Renote Access API du wiki de Hudson.