jenkins_api_client 0.8.1 → 0.9.0

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 1.9.3
   - 1.9.2
   - jruby-18mode

data/CHANGELOG.md

@@ -4,6 +4,18 @@ CHANGELOG
 upcoming
 --------
 
+v0.9.0  [10-MAR-2013]
+---------------------
+* Added capability to send email notification to existing jobs
+* Removed warnings from client.rb
+* Refactored and improved exception handling
+* A bug is fixed in client which allows only the valid params as options. Credit: @Niarfe
+* Added a timeout parameter for waiting for jenkins to become ready. Credit: @Niarfe
+* Added function to reload jenkins. Credit: @missedone
+* Fixed a bug where jenkins_path was missing in get_config and post_config. Credit: @cylol
+* Added capability to obtain jenkins version and other useful information
+* Added new tests for various cases, and other code improvements
+
 v0.8.1  [15-FEB-2013]
 ---------------------
 * Fixed a bug in creating view. Issue #42

data/Rakefile

@@ -35,3 +35,8 @@ RSpec::Core::RakeTask.new(:func_tests) do |spec|
   spec.pattern = FileList['spec/func_tests/*_spec.rb']
   spec.rspec_opts = ['--color', '--format documentation']
 end
+
+RSpec::Core::RakeTask.new(:test) do |spec|
+  spec.pattern = FileList['spec/*/*.rb']
+  spec.rspec_opts = ['--color', '--format documentation']
+end

data/lib/jenkins_api_client/build_queue.rb

@@ -60,7 +60,7 @@ module JenkinsApi
       #
       # @param [String] task_name Name of the task/job
       #
-      # @return [FixNum] age in seconds
+      # @return [Fixnum] age in seconds
       #
       def get_age(task_name)
         age = nil
@@ -96,7 +96,10 @@ module JenkinsApi
         causes = nil
         details = get_details(task_name)
         unless details.empty?
-          causes = details["actions"]["causes"]
+          causes = []
+          details["actions"].each do |action|
+            causes << action["causes"]
+          end
         end
         causes
       end
@@ -118,7 +121,7 @@ module JenkinsApi
 
       # Obtains the ETA given by Jenkins if any
       #
-      # @param[String] task_name name of the task
+      # @param [String] task_name name of the task
       #
       # @return [String] ETA for the task, nil if no task found and N/A for
       #                  tasks with no ETA info.
@@ -179,7 +182,7 @@ module JenkinsApi
         buildable = nil
         details = get_details(task_name)
         unless details.empty?
-          buildable = details["buildable"] == "true" ? true : false
+          buildable = details["buildable"]
         end
         buildable
       end
@@ -194,7 +197,7 @@ module JenkinsApi
         blocked = nil
         details = get_details(task_name)
         unless details.empty?
-          blocked = details["blocked"] == "true" ? true : false
+          blocked = details["blocked"]
         end
         blocked
       end
@@ -209,7 +212,7 @@ module JenkinsApi
         stuck = nil
         details = get_details(task_name)
         unless details.empty?
-          stuck = details["stuck"] == "true" ? true : false
+          stuck = details["stuck"]
         end
         stuck
       end

data/lib/jenkins_api_client/cli/base.rb

@@ -22,7 +22,6 @@
 
 require 'thor'
 require 'thor/group'
-require "#{File.dirname(__FILE__)}/../client.rb"
 require "#{File.dirname(__FILE__)}/node.rb"
 require "#{File.dirname(__FILE__)}/job.rb"
 require "#{File.dirname(__FILE__)}/system.rb"

data/lib/jenkins_api_client/cli/system.rb

@@ -40,6 +40,12 @@ module JenkinsApi
         @client.system.cancel_quiet_down
       end
 
+      desc "reload", "Reload Jenkins server"
+      def reload
+        @client = Helper.setup(parent_options)
+        @client.system.reload
+      end
+
       desc "restart", "Restarts the Jenkins server"
       method_option :force, :type => :boolean, :aliases => "-s",
         :desc => "Force restart"

data/lib/jenkins_api_client/client.rb

@@ -30,9 +30,19 @@ require 'base64'
 
 module JenkinsApi
   class Client
-    attr_accessor :debug
+    attr_accessor :debug, :timeout
     DEFAULT_SERVER_PORT = 8080
-    VALID_PARAMS = %w(server_ip server_port jenkins_path username password debug)
+    DEFAULT_TIMEOUT = 120
+    VALID_PARAMS = [
+      "server_ip",
+      "server_port",
+      "jenkins_path",
+      "username",
+      "password",
+      "password_base64",
+      "debug",
+      "timeout"
+    ].freeze
 
     # Initialize a Client object with Jenkins CI server credentials
     #
@@ -44,13 +54,16 @@ module JenkinsApi
     #
     def initialize(args)
       args.each do |key, value|
-        instance_variable_set("@#{key}", value) if value
+        if value && VALID_PARAMS.include?(key.to_s)
+          instance_variable_set("@#{key}", value)
+        end
       end if args.is_a? Hash
      raise "Server IP is required to connect to Jenkins" unless @server_ip
      unless @username && (@password || @password_base64)
        raise "Credentials are required to connect to te Jenkins Server"
      end
      @server_port = DEFAULT_SERVER_PORT unless @server_port
+     @timeout = DEFAULT_TIMEOUT unless @timeout
      @debug = false unless @debug
 
      # Base64 decode inserts a newline character at the end. As a workaround
@@ -128,23 +141,7 @@ module JenkinsApi
       puts "[INFO] GET #{to_get}" if @debug
       request.basic_auth @username, @password
       response = http.request(request)
-      msg = "HTTP Code: #{response.code}, Response Body: #{response.body}"
-      case response.code.to_i
-      when 200
-        if url_suffix =~ /json/
-          return JSON.parse(response.body)
-        else
-          return response
-        end
-      when 401
-        raise Exceptions::UnautherizedException.new(msg)
-      when 404
-        raise Exceptions::NotFoundException.new(msg)
-      when 500
-        raise Exceptions::InternelServerErrorException.new(msg)
-      else
-        raise Exceptions::ApiException.new(msg)
-      end
+      handle_exception(response, "body", url_suffix =~ /json/)
     end
 
     # Sends a POST message to the Jenkins CI server with the specified URL
@@ -161,17 +158,7 @@ module JenkinsApi
       request.content_type = 'application/json'
       request.set_form_data(form_data) unless form_data.nil?
       response = http.request(request)
-      msg = "HTTP Code: #{response.code}, Response Body: #{response.body}"
-      case response.code.to_i
-      when 200, 302
-        return response.body
-      when 404
-        raise Exceptions::NotFoundException.new(msg)
-      when 500
-        raise Exceptions::InternelServerErrorException.new(msg)
-      else
-        raise Exceptions::ApiException.new(msg)
-      end
+      handle_exception(response)
     end
 
     # Obtains the configuration of a component from the Jenkins CI server
@@ -179,13 +166,13 @@ module JenkinsApi
     # @param [String] url_prefix
     #
     def get_config(url_prefix)
-      url_prefix = URI.escape(url_prefix)
+      url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Get.new("#{url_prefix}/config.xml")
       puts "[INFO] GET #{url_prefix}/config.xml" if @debug
       request.basic_auth @username, @password
       response = http.request(request)
-      response.body
+      handle_exception(response, "body")
     end
 
     # Posts the given xml configuration to the url given
@@ -194,7 +181,7 @@ module JenkinsApi
     # @param [String] xml
     #
     def post_config(url_prefix, xml)
-      url_prefix = URI.escape(url_prefix)
+      url_prefix = URI.escape("#{@jenkins_path}#{url_prefix}")
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Post.new("#{url_prefix}")
       puts "[INFO] PUT #{url_prefix}" if @debug
@@ -202,7 +189,58 @@ module JenkinsApi
       request.body = xml
       request.content_type = 'application/xml'
       response = http.request(request)
-      response.body
+      handle_exception(response)
+    end
+
+    # Obtain the version of Jenkins CI server
+    #
+    # @return [String] Version of Jenkins
+    #
+    def get_jenkins_version
+      response = get_root
+      response["X-Jenkins"]
+    end
+
+    # Obtain the Hudson version of the CI server
+    #
+    # @return [String] Version of Hudson on Jenkins server
+    #
+    def get_hudson_version
+      response = get_root
+      response["X-Hudson"]
+    end
+
+    # Obtain the date of the Jenkins server
+    #
+    # @return [String] Server date
+    #
+    def get_server_date
+      response = get_root
+      response["Date"]
+    end
+
+    private
+
+    def handle_exception(response, to_send = "code", send_json = false)
+      msg = "HTTP Code: #{response.code}, Response Body: #{response.body}"
+      case response.code.to_i
+      when 200, 302
+        if to_send == "body" && send_json
+          return JSON.parse(response.body)
+        elsif to_send == "body"
+          return response.body
+        elsif to_send == "code"
+          return response.code
+        end
+      when 401
+        raise Exceptions::UnautherizedException.new
+      when 404
+        raise Exceptions::NotFoundException.new
+      when 500
+        raise Exceptions::InternelServerErrorException.new
+      else
+        raise Exceptions::ApiException.new
+      end
     end
 
   end

data/lib/jenkins_api_client/exceptions.rb

@@ -36,13 +36,17 @@ module JenkinsApi
 
     class NotFoundException < ApiException
       def initialize(message = "")
-        super("Requested page not found on the Jenkins CI server. #{message}")
+        super("Requested component is not found on the Jenkins CI server." +
+              " #{message}")
       end
     end
 
     class InternelServerErrorException < ApiException
       def initialize(message = "")
-        super("Internel Server Error. #{message}")
+        super("Internel Server Error. Perhaps the in-memory configuration of" +
+              " Jenkins is different from the disk configuration." +
+              " Please try to reload the configuration #{message}"
+             )
       end
     end
   end

data/lib/jenkins_api_client/job.rb

@@ -55,7 +55,7 @@ module JenkinsApi
       #  * +:block_build_when_downstream_building+ true or false
       #  * +:block_build_when_upstream_building+ true or false
       #  * +:concurrent_build+ true or false
-      #  * +:scm_provider+ type of source control system. Supported: Git, SVN
+      #  * +:scm_provider+ type of source control. Supported: Git, SVN, and CVS
       #  * +:scm_url+ remote url for scm
       #  * +:scm_module+ Module to download. Only for CVS.
       #  * +:scm_branch+ branch to use in scm. Uses master by default
@@ -111,7 +111,7 @@ module JenkinsApi
         end
         params[:concurrent_build] = false if params[:concurrent_build].nil?
         if params[:notification_email]
-          if params[:notification_email_for_every_unstable_build].nil?
+          if params[:notification_email_for_every_unstable].nil?
             params[:notification_email_for_every_unstable] = false
           end
           if params[:notification_email_send_to_individuals].nil?
@@ -148,82 +148,14 @@ module JenkinsApi
             xml.properties
             # SCM related stuff
             if params[:scm_provider] == 'subversion'
-              xml.scm(:class => "hudson.scm.SubversionSCM",
-                      :plugin => "subversion@1.39") {
-                xml.locations {
-                  xml.send("hudson.scm.SubversionSCM_-ModuleLocation") {
-                    xml.remote "#{params[:scm_url]}"
-                    xml.local "."
-                  }
-                }
-                xml.excludedRegions
-                xml.includedRegions
-                xml.excludedUsers
-                xml.excludedRevprop
-                xml.excludedCommitMessages
-                xml.workspaceUpdater(:class =>
-                                     "hudson.scm.subversion.UpdateUpdater")
-              }
+              # Build subversion related XML portion
+              scm_subversion(params, xml)
             elsif params[:scm_provider] == "cvs"
-              xml.scm(:class => "hudson.scm.CVSSCM",
-                      :plugin => "cvs@1.6") {
-                xml.cvsroot "#{params[:scm_url]}"
-                xml.module "#{params[:scm_module]}"
-                if params[:scm_branch]
-                  xml.branch "#{params[:scm_branch]}"
-                else
-                  xml.branch "#{params[:scm_tag]}"
-                end
-                xml.canUseUpdate true
-                xml.useHeadIfNotFound(
-                  "#{params[:scm_use_head_if_tag_not_found]}")
-                xml.flatten true
-                if params[:scm_tag]
-                  xml.isTag true
-                else
-                  xml.isTag false
-                end
-                xml.excludedRegions
-              }
+              # Build CVS related XML portion
+              scm_cvs(params, xml)
             elsif params[:scm_provider] == "git"
-              xml.scm(:class => "hudson.plugins.git.GitSCM") {
-                xml.configVersion "2"
-                xml.userRemoteConfigs {
-                  xml.send("hudson.plugins.git.UserRemoteConfig") {
-                    xml.name
-                    xml.refspec
-                    xml.url "#{params[:scm_url]}"
-                  }
-                }
-                xml.branches {
-                  xml.send("hudson.plugins.git.BranchSpec") {
-                    xml.name "#{params[:scm_branch]}"
-                  }
-                }
-                xml.disableSubmodules "false"
-                xml.recursiveSubmodules "false"
-                xml.doGenerateSubmoduleConfigurations "false"
-                xml.authorOrCommitter "false"
-                xml.clean "false"
-                xml.wipeOutWorkspace "false"
-                xml.pruneBranches "false"
-                xml.remotePoll "false"
-                xml.ignoreNotifyCommit "false"
-                xml.useShallowClone "false"
-                xml.buildChooser(:class =>
-                                 "hudson.plugins.git.util.DefaultBuildChooser")
-                xml.gitTool "Default"
-                xml.submoduleCfg(:class => "list")
-                xml.relativeTargetDir
-                xml.reference
-                xml.excludedRegions
-                xml.excludedUsers
-                xml.gitConfigName
-                xml.gitConfigEmail
-                xml.skipTag "false"
-                xml.includedRegions
-                xml.scmName
-              }
+              # Build Git related XML portion
+              scm_git(params, xml)
             else
               xml.scm(:class => "hudson.scm.NullSCM")
             end
@@ -259,27 +191,11 @@ module JenkinsApi
             }
             # Adding Downstream projects
             xml.publishers {
-              if params[:child_projects]
-                xml.send("hudson.tasks.BuildTrigger") {
-                  xml.childProjects "#{params[:child_projects]}"
-                  threshold = params[:child_threshold]
-                  name, ordinal, color = get_threshold_params(threshold)
-                  xml.threshold {
-                    xml.name "#{name}"
-                    xml.ordinal "#{ordinal}"
-                    xml.color "#{color}"
-                  }
-                }
-              end
-              if params[:notification_email]
-                xml.send("hudson.tasks.Mailer") {
-                  xml.recipients "#{params[:notification_email]}"
-                  xml.dontNotifyEveryUnstableBuild(
-                    "#{params[:notification_email_for_every_unstable]}")
-                  xml.sendToIndividuals(
-                    "#{params[:notification_email_send_to_individuals]}")
-                }
-              end
+              # Build portion of XML that adds child projects
+              child_projects(params, xml) if params[:child_projects]
+              # Build portion of XML that adds email notification
+              notification_email(params, xml) if params[:notification_email]
+              # Build portion of XML that adds skype notification
               skype_notification(params, xml) if params[:skype_targets]
             }
             xml.buildWrappers
@@ -288,6 +204,30 @@ module JenkinsApi
         create(params[:name], builder.to_xml)
       end
 
+      # Adding email notification to a job
+      #
+      # @param [Hash] params parameters to add email notification
+      # @option params [String] :name Name of the job
+      # @option params [String] :notification_email Email address to send
+      # @option params [TrueClass|FalseClass] :notification_email_for_every_unstable
+      # Send email notification email for every unstable build
+      def add_email_notification(params)
+        raise "No job name specified" unless params[:name]
+        raise "No email address specified" unless params[:notification_email]
+        xml = get_config(params[:name])
+        n_xml = Nokogiri::XML(xml)
+        if n_xml.xpath("//hudson.tasks.Mailer").empty?
+          p_xml = Nokogiri::XML::Builder.new(:encoding => "UTF-8") { |xml|
+            notification_email(params, xml)
+          }
+          email_xml = Nokogiri::XML(p_xml.to_xml).xpath(
+            "//hudson.tasks.Mailer"
+          ).first
+          n_xml.xpath("//publishers").first.add_child(email_xml)
+          post_config(params[:name], n_xml.to_xml)
+        end
+      end
+
       # Adding skype notificaiton to a job
       #
       # @param [Hash] params parameters for adding skype notification
@@ -313,7 +253,6 @@ module JenkinsApi
         raise "No Skype target specified" unless params[:skype_targets]
         xml = get_config(params[:name])
         n_xml = Nokogiri::XML(xml)
-        puts n_xml.xpath("//hudson.plugins.skype.im.transport.SkypePublisher")
         if n_xml.xpath("//hudson.plugins.skype.im.transport.SkypePublisher").empty?
           p_xml = Nokogiri::XML::Builder.new(:encoding => "UTF-8") { |xml|
             skype_notification(params, xml)
@@ -399,7 +338,7 @@ module JenkinsApi
       # @return [Hash] response
       #   * +output+ Console output of the job
       #   * +size+ Size of the text. This can be used as 'start' for the
-      #            next call to get progressive output
+      #   next call to get progressive output
       #   * +more+ More data available for the job. 'true' if available
       #            and nil otherwise
       #
@@ -817,31 +756,6 @@ module JenkinsApi
         params_array
       end
 
-      # Obtains the threshold params used by jenkins in the XML file
-      # given the threshold
-      #
-      # @param [String] threshold success, failure, or unstable
-      #
-      # @return [String] status readable status matching the color
-      #
-      def get_threshold_params(threshold)
-        case threshold
-        when 'success'
-          name = 'SUCCESS'
-          ordinal = 0
-          color = 'BLUE'
-        when 'unstable'
-          name = 'UNSTABLE'
-          ordinal = 1
-          color = 'YELLOW'
-        when 'failure'
-          name = 'FAILURE'
-          ordinal = 2
-          color = 'RED'
-        end
-        return name, ordinal, color
-      end
-
       # Add downstream projects to a specific job given the job name,
       # projects to be added as downstream projects, and the threshold
       #
@@ -999,6 +913,130 @@ module JenkinsApi
 
       private
 
+      # Obtains the threshold params used by jenkins in the XML file
+      # given the threshold
+      #
+      # @param [String] threshold success, failure, or unstable
+      #
+      # @return [String] status readable status matching the color
+      #
+      def get_threshold_params(threshold)
+        case threshold
+        when 'success'
+          name = 'SUCCESS'
+          ordinal = 0
+          color = 'BLUE'
+        when 'unstable'
+          name = 'UNSTABLE'
+          ordinal = 1
+          color = 'YELLOW'
+        when 'failure'
+          name = 'FAILURE'
+          ordinal = 2
+          color = 'RED'
+        end
+        return name, ordinal, color
+      end
+
+      # This private method builds portion of XML that adds subversion SCM
+      # to a Job
+      #
+      # @param [Hash] params parameters to be used for building XML
+      # @param [XML] xml Nokogiri XML object
+      #
+      def scm_subversion(params, xml)
+        xml.scm(:class => "hudson.scm.SubversionSCM",
+               :plugin => "subversion@1.39") {
+         xml.locations {
+           xml.send("hudson.scm.SubversionSCM_-ModuleLocation") {
+             xml.remote "#{params[:scm_url]}"
+             xml.local "."
+           }
+         }
+         xml.excludedRegions
+         xml.includedRegions
+         xml.excludedUsers
+         xml.excludedRevprop
+         xml.excludedCommitMessages
+         xml.workspaceUpdater(:class =>
+                              "hudson.scm.subversion.UpdateUpdater")
+        }
+      end
+
+      # This private method builds portion of XML that adds CVS SCM to a Job
+      #
+      # @param [Hash] params parameters to be used for building XML
+      # @param [XML] xml Nokogiri XML object
+      #
+      def scm_cvs(params, xml)
+        xml.scm(:class => "hudson.scm.CVSSCM",
+                :plugin => "cvs@1.6") {
+          xml.cvsroot "#{params[:scm_url]}"
+          xml.module "#{params[:scm_module]}"
+          if params[:scm_branch]
+            xml.branch "#{params[:scm_branch]}"
+          else
+            xml.branch "#{params[:scm_tag]}"
+          end
+          xml.canUseUpdate true
+          xml.useHeadIfNotFound(
+            "#{params[:scm_use_head_if_tag_not_found]}")
+          xml.flatten true
+          if params[:scm_tag]
+            xml.isTag true
+          else
+            xml.isTag false
+          end
+          xml.excludedRegions
+        }
+      end
+
+      # This private method adds portion of XML that adds Git SCM to a Job
+      #
+      # @param [Hash] params parameters to be used for building XML
+      # @param [XML] xml Nokogiri XML object
+      #
+      def scm_git(params, xml)
+        xml.scm(:class => "hudson.plugins.git.GitSCM") {
+          xml.configVersion "2"
+          xml.userRemoteConfigs {
+            xml.send("hudson.plugins.git.UserRemoteConfig") {
+              xml.name
+              xml.refspec
+              xml.url "#{params[:scm_url]}"
+            }
+          }
+          xml.branches {
+            xml.send("hudson.plugins.git.BranchSpec") {
+              xml.name "#{params[:scm_branch]}"
+            }
+          }
+          xml.disableSubmodules "false"
+          xml.recursiveSubmodules "false"
+          xml.doGenerateSubmoduleConfigurations "false"
+          xml.authorOrCommitter "false"
+          xml.clean "false"
+          xml.wipeOutWorkspace "false"
+          xml.pruneBranches "false"
+          xml.remotePoll "false"
+          xml.ignoreNotifyCommit "false"
+          xml.useShallowClone "false"
+          xml.buildChooser(:class =>
+                           "hudson.plugins.git.util.DefaultBuildChooser")
+          xml.gitTool "Default"
+          xml.submoduleCfg(:class => "list")
+          xml.relativeTargetDir
+          xml.reference
+          xml.excludedRegions
+          xml.excludedUsers
+          xml.gitConfigName
+          xml.gitConfigEmail
+          xml.skipTag "false"
+          xml.includedRegions
+          xml.scmName
+        }
+      end
+
       # Method for creating portion of xml that builds Skype notification
       # Use this option only when you have the Skype plugin installed and
       # everything is set up properly
@@ -1069,6 +1107,42 @@ module JenkinsApi
         }
       end
 
+      # This private method builds portion of XML that adds notification email
+      # to a Job.
+      #
+      # @param [Hash] params parameters to be used for building XML
+      # @param [XML] xml Nokogiri XML object
+      #
+      def notification_email(params, xml)
+        if params[:notification_email]
+          xml.send("hudson.tasks.Mailer") {
+            xml.recipients "#{params[:notification_email]}"
+            xml.dontNotifyEveryUnstableBuild(
+              "#{params[:notification_email_for_every_unstable]}")
+            xml.sendToIndividuals(
+              "#{params[:notification_email_send_to_individuals]}")
+          }
+        end
+      end
+
+      # This private method builds portion of XML that adds child projects
+      # to a Job.
+      #
+      # @param [Hash] params parameters to be used for building XML
+      # @param [XML] xml Nokogiri XML object
+      #
+      def child_projects(params, xml)
+        xml.send("hudson.tasks.BuildTrigger") {
+          xml.childProjects "#{params[:child_projects]}"
+          threshold = params[:child_threshold]
+          name, ordinal, color = get_threshold_params(threshold)
+          xml.threshold {
+            xml.name "#{name}"
+            xml.ordinal "#{ordinal}"
+            xml.color "#{color}"
+          }
+        }
+      end
     end
   end
 end