jenkins_api_client 0.12.1 → 0.13.0

data/lib/jenkins_api_client/exceptions.rb

@@ -20,6 +20,8 @@
 # THE SOFTWARE.
 #
 
+require 'logger'
+
 module JenkinsApi
   # This module contains classes that define exceptions for various catories.
   #
@@ -28,8 +30,9 @@ module JenkinsApi
     # RuntimeError.
     #
     class ApiException < RuntimeError
-      def initialize(message = "")
-        super("Error: #{message}")
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        logger.add(log_level) { "#{self.class}: #{message}" }
+        super(message)
       end
     end
 
@@ -37,57 +40,142 @@ module JenkinsApi
     # but not provided.
     #
     class NothingSubmitted < ApiException
-      def initialize(message = "")
-        super("Nothing is submitted. #{message}")
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Nothing is submitted. #{message}"
+        super(logger, msg)
       end
     end
 
     # This exception class handles cases where a job not able to be created
     # because it already exists.
     #
-    class JobAlreadyExistsWithName < ApiException
-      def initialize(message = "")
-        super("Job already exists with that name. #{message}")
+    class JobAlreadyExists < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        super(logger, message)
+      end
+    end
+    # Support for backward compatibility
+    JobAlreadyExistsWithName = JobAlreadyExists
+
+    class ViewAlreadyExists < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        super(logger, message)
+      end
+    end
+
+    class NodeAlreadyExists < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        super(logger, message)
+      end
+    end
+
+    # This exception class handles cases where invalid credentials are provided
+    # to connect to the Jenkins.
+    #
+    class Unauthorized < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Invalid credentials are provided. #{message}"
+        super(logger, msg, Logger::FATAL)
       end
     end
+    UnauthorizedException = Unauthorized
 
     # This exception class handles cases where invalid credentials are provided
     # to connect to the Jenkins.
     #
-    class UnautherizedException < ApiException
-      def initialize(message = "")
-        super("Invalid credentials are provided. #{message}")
+    class Forbidden < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "The Crumb was expired or not sent to the server." +
+              " Perhaps the CSRF protection was not enabled on the server" +
+              " when the client was initialized. Please re-initialize the" +
+              " client. #{message}"
+        super(logger, msg)
+      end
+    end
+    # Support for backward compatibility
+    ForbiddenException = Forbidden
+
+    # This exception class handles cases where a requested page is not found on
+    # the Jenkins API.
+    #
+    class NotFound < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Requested component is not found on the Jenkins CI server." \
+          if message.empty?
+        super(logger, msg)
       end
     end
+    # Support for backward compatibility
+    NotFoundException = NotFound
 
     # This exception class handles cases where a requested page is not found on
     # the Jenkins API.
     #
-    class NotFoundException < ApiException
-      def initialize(message = "")
-        super("Requested component is not found on the Jenkins CI server." +
-              " #{message}")
+    class CrumbNotFound < NotFound
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "No crumb available on the server. #{message}"
+        super(logger, msg)
+      end
+    end
+
+    class JobNotFound < NotFound
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "The specified job is not found" if message.empty?
+        super(logger, msg)
+      end
+    end
+
+    class ViewNotFound < NotFound
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "The specified view is not found" if message.empty?
+        super(logger, msg)
+      end
+    end
+
+    class NodeNotFound < NotFound
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "The specified node is not found" if message.empty?
+        super(logger, msg)
       end
     end
 
     # This exception class handles cases where the Jenkins API returns with a
     # 500 Internel Server Error.
     #
-    class InternelServerErrorException < ApiException
-      def initialize(message = "")
-        super("Internel Server Error. Perhaps the in-memory configuration of" +
+    class InternalServerError < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Internel Server Error. Perhaps the in-memory configuration of" +
               " Jenkins is different from the disk configuration." +
               " Please try to reload the configuration #{message}"
-             )
+        super(logger, msg)
+      end
+    end
+    # Support for backward compatibility
+    InternalServerErrorException = InternalServerError
+
+    # This exception class handles cases where the Jenkins is getting restarted
+    # or reloaded where the response code returned is 503
+    #
+    class ServiceUnavailable < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Jenkins is being reloaded or restarted. Please wait till" +
+              " Jenkins is completely back online. This can be" +
+              " programatically achieved by System#wait_for_ready #{message}"
+        super(logger, msg)
       end
     end
+    # Support for backward compatibility
+    ServiceUnavailableException = ServiceUnavailable
 
     # Exception occurred while running java CLI commands
     #
-    class CLIException < ApiException
-      def initialize(message = "")
-        super("Execute CLI Error. #{message}")
+    class CLIError < ApiException
+      def initialize(logger, message = "", log_level = Logger::ERROR)
+        msg = "Execute CLI Error. #{message}"
+        super(logger, msg)
       end
     end
+    # Support for backward compatibility
+    CLIException = CLIError
   end
 end

data/lib/jenkins_api_client/job.rb

@@ -31,6 +31,7 @@ module JenkinsApi
       #
       def initialize(client)
         @client = client
+        @logger = @client.logger
       end
 
       # Return a string representation of the object
@@ -45,6 +46,7 @@ module JenkinsApi
       # @param [XML] xml
       #
       def create(job_name, xml)
+        @logger.info "Creating job '#{job_name}'"
         @client.post_config("/createItem?name=#{job_name}", xml)
       end
 
@@ -102,7 +104,8 @@ module JenkinsApi
         supported_scm = ["git", "subversion", "cvs"]
 
         # Set default values for params that are not specified.
-        raise 'Job name must be specified' unless params[:name]
+        raise ArgumentError, "Job name must be specified" \
+          unless params.is_a?(Hash) && params[:name]
         if params[:keep_dependencies].nil?
           params[:keep_dependencies] = false
         end
@@ -142,6 +145,8 @@ module JenkinsApi
           params[:child_threshold] = 'failure'
         end
 
+        @logger.debug "Creating a freestyle job with params: #{params.inspect}"
+
         # Build the Job xml file based on the parameters given
         builder = Nokogiri::XML::Builder.new(:encoding => 'UTF-8') { |xml|
           xml.project {
@@ -210,6 +215,7 @@ module JenkinsApi
       # 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
@@ -218,6 +224,8 @@ module JenkinsApi
       def add_email_notification(params)
         raise "No job name specified" unless params[:name]
         raise "No email address specified" unless params[:notification_email]
+        @logger.info "Adding '#{params[:notification_email]}' to be" +
+          " notified for '#{params[:name]}'"
         xml = get_config(params[:name])
         n_xml = Nokogiri::XML(xml)
         if n_xml.xpath("//hudson.tasks.Mailer").empty?
@@ -255,6 +263,7 @@ module JenkinsApi
       def add_skype_notification(params)
         raise "No job name specified" unless params[:name]
         raise "No Skype target specified" unless params[:skype_targets]
+        @logger.info "Adding Skype notification for '#{params[:name]}'"
         xml = get_config(params[:name])
         n_xml = Nokogiri::XML(xml)
         if n_xml.xpath("//hudson.plugins.skype.im.transport.SkypePublisher").empty?
@@ -275,6 +284,7 @@ module JenkinsApi
       # @param [String] new_job Name of the new job.
       #
       def rename(old_job, new_job)
+        @logger.info "Renaming job '#{old_job}' to '#{new_job}'"
         @client.api_post_request("/job/#{old_job}/doRename?newName=#{new_job}")
       end
 
@@ -283,6 +293,7 @@ module JenkinsApi
       # @param [String] job_name
       #
       def delete(job_name)
+        @logger.info "Deleting job '#{job_name}'"
         @client.api_post_request("/job/#{job_name}/doDelete")
       end
 
@@ -292,9 +303,19 @@ module JenkinsApi
       #       caution.
       #
       def delete_all!
+        @logger.info "Deleting all jobs from jenkins"
         list_all.each { |job| delete(job) }
       end
 
+      # Wipe out the workspace for a job given the name
+      #
+      # @param [String] job_name
+      #
+      def wipe_out_workspace(job_name)
+        @logger.info "Wiping out the workspace of job '#{job_name}'"
+        @client.api_post_request("/job/#{job_name}/doWipeOutWorkspace")
+      end
+
       # Stops a running build of a job
       # This method will stop the current/most recent build if no build number
       # is specified. The build will be stopped only if it was
@@ -306,6 +327,7 @@ module JenkinsApi
       def stop_build(job_name, build_number = 0)
         build_number = get_current_build_number(job_name) if build_number == 0
         raise "No builds for #{job_name}" unless build_number
+        @logger.info "Stopping job '#{job_name}' Build ##{build_number}"
         # Check and see if the build is running
         is_building = @client.api_get_request(
           "/job/#{job_name}/#{build_number}"
@@ -321,11 +343,25 @@ module JenkinsApi
       # @param [String] job_name
       #
       def recreate(job_name)
+        @logger.info "Recreating job '#{job_name}'"
         job_xml = get_config(job_name)
         delete(job_name)
         create(job_name, job_xml)
       end
 
+      # Copy a job
+      #
+      # @param [String] from_job_name
+      # @param [String] to_job_name
+      #
+      def copy(from_job_name, to_job_name=nil)
+        to_job_name = "copy_of_#{from_job_name}" if to_job_name.nil?
+        @logger.info "Copying job '#{from_job_name}' to '#{to_job_name}'"
+        @client.api_post_request(
+          "/createItem?name=#{to_job_name}&mode=copy&from=#{from_job_name}"
+        )
+      end
+
       # Get progressive console output from Jenkins server for a job
       #
       # @param [String] job_name Name of the Jenkins job
@@ -392,9 +428,10 @@ module JenkinsApi
       #
       def list_by_status(status, jobs = [])
         jobs = list_all if jobs.empty?
-        xml_response = @client.api_get_request("", "tree=jobs[name,color]")
+        @logger.info "Obtaining jobs matching status '#{status}'"
+        json_response = @client.api_get_request("", "tree=jobs[name,color]")
         filtered_jobs = []
-        xml_response["jobs"].each do |job|
+        json_response["jobs"].each do |job|
           if color_to_status(job["color"]) == status &&
              jobs.include?(job["name"])
             filtered_jobs << job["name"]
@@ -409,6 +446,7 @@ module JenkinsApi
       # @param [Boolean] ignorecase
       #
       def list(filter, ignorecase = true)
+        @logger.info "Obtaining jobs matching filter '#{filter}'"
         response_json = @client.api_get_request("")
         jobs = []
         response_json["jobs"].each do |job|
@@ -424,8 +462,9 @@ module JenkinsApi
       # List all jobs on the Jenkins CI server along with their details
       #
       def list_all_with_details
-       response_json = @client.api_get_request("")
-       response_json["jobs"]
+        @logger.info "Obtaining the details of all jobs"
+        response_json = @client.api_get_request("")
+        response_json["jobs"]
       end
 
       # List details of a specific job
@@ -433,6 +472,7 @@ module JenkinsApi
       # @param [String] job_name
       #
       def list_details(job_name)
+        @logger.info "Obtaining the details of '#{job_name}'"
         @client.api_get_request("/job/#{job_name}")
       end
 
@@ -441,6 +481,7 @@ module JenkinsApi
       # @param [String] job_name
       #
       def get_upstream_projects(job_name)
+        @logger.info "Obtaining the upstream projects of '#{job_name}'"
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["upstreamProjects"]
       end
@@ -450,6 +491,7 @@ module JenkinsApi
       # @param [String] job_name
       #
       def get_downstream_projects(job_name)
+        @logger.info "Obtaining the down stream projects of '#{job_name}'"
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["downstreamProjects"]
       end
@@ -459,6 +501,7 @@ module JenkinsApi
       # @param [String] job_name
       #
       def get_builds(job_name)
+        @logger.info "Obtaining the build details of '#{job_name}'"
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["builds"]
       end
@@ -500,6 +543,7 @@ module JenkinsApi
       # @return [String] status current status of the given job
       #
       def get_current_build_status(job_name)
+        @logger.info "Obtaining the current build status of '#{job_name}'"
         response_json = @client.api_get_request("/job/#{job_name}")
         color_to_status(response_json["color"])
       end
@@ -512,23 +556,78 @@ module JenkinsApi
       # @return [Number] build_unumber current build number of the given job
       #
       def get_current_build_number(job_name)
+        @logger.info "Obtaining the current build number of '#{job_name}'"
         @client.api_get_request("/job/#{job_name}")['nextBuildNumber'].to_i - 1
       end
 
       # Build a job given the name of the job
-      # You can optionally pass in a list of params for Jenkins to use for parameterized builds
+      # You can optionally pass in a list of params for Jenkins to use for
+      # parameterized builds
+      #
+      # @param [String] job_name the name of the job
+      # @param [Hash] params the parameters for parameterized builds
+      # @param [Boolean] return_build_number whether to wait and obtain the build
+      #   number
+      #
+      # @return [String, Integer] the response code from the build POST request
+      #   if return_build_number is not requested and the build number if the
+      #   return_build_number is requested. nil will be returned if the build
+      #   number is requested and not available. This can happen if there is
+      #   already a job in the queue and concurrent build is disabled.
+      #
+      def build(job_name, params={}, return_build_number = false)
+        msg = "Building job '#{job_name}'"
+        msg << " with parameters: #{params.inspect}" unless params.empty?
+        @logger.info msg
+        build_endpoint = params.empty? ? "build" : "buildWithParameters"
+        raw_response = return_build_number
+        response =@client.api_post_request(
+          "/job/#{job_name}/#{build_endpoint}",
+          params,
+          raw_response
+        )
+        # If return_build_number is enabled, obtain the queue ID from the location
+        # header and wait till the build is moved to one of the executors and a
+        # build number is assigned
+        if return_build_number
+          if response["location"]
+            task_id_match = response["location"].match(/\/item\/(\d*)\//)
+            task_id = task_id_match.nil? ? nil : task_id_match[1]
+            unless task_id.nil?
+              @logger.debug "Queue task ID for job '#{job_name}': #{task_id}"
+              Timeout::timeout(@client.timeout) do
+                while @client.queue.get_item_by_id(task_id)["executable"].nil?
+                  sleep 5
+                end
+              end
+              @client.queue.get_item_by_id(task_id)["executable"]["number"]
+            else
+              nil
+            end
+          else
+            nil
+          end
+        else
+          response
+        end
+      end
+
+      # Enable a job given the name of the job
       #
       # @param [String] job_name
-      # @param [Hash] params
       #
-      # @return [String] response_code return code from HTTP POST
+      def enable(job_name)
+        @logger.info "Enabling job '#{job_name}'"
+        @client.api_post_request("/job/#{job_name}/enable")
+      end
+
+      # Disable a job given the name of the job
       #
-      def build(job_name, params={})
-        if params.empty?
-          @client.api_post_request("/job/#{job_name}/build")
-        else
-          @client.api_post_request("/job/#{job_name}/buildWithParameters", params)
-        end
+      # @param [String] job_name
+      #
+      def disable(job_name)
+        @logger.info "Disabling job '#{job_name}'"
+        @client.api_post_request("/job/#{job_name}/disable")
       end
 
       # Obtain the configuration stored in config.xml of a specific job
@@ -538,6 +637,7 @@ module JenkinsApi
       # @return [String] XML Config.xml of the job
       #
       def get_config(job_name)
+        @logger.info "Obtaining the config.xml of '#{job_name}'"
         @client.get_config("/job/#{job_name}")
       end
 
@@ -549,6 +649,7 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def post_config(job_name, xml)
+        @logger.info "Posting the config.xml of '#{job_name}'"
         @client.post_config("/job/#{job_name}/config.xml", xml)
       end
 
@@ -559,9 +660,10 @@ module JenkinsApi
       #
       def get_test_results(job_name, build_num)
         build_num = get_current_build_number(job_name) if build_num == 0
-
+        @logger.info "Obtaining the test results of '#{job_name}'" +
+          " Build ##{build_num}"
         @client.api_get_request("/job/#{job_name}/#{build_num}/testReport")
-      rescue Exceptions::NotFoundException
+      rescue Exceptions::NotFound
         # Not found is acceptable, as not all builds will have test results
         # and this is what jenkins throws at us in that case
         nil
@@ -574,6 +676,8 @@ module JenkinsApi
       #
       def get_build_details(job_name, build_num)
         build_num = get_current_build_number(job_name) if build_num == 0
+        @logger.info "Obtaining the build details of '#{job_name}'" +
+          " Build ##{build_num}"
 
         @client.api_get_request("/job/#{job_name}/#{build_num}/")
       end
@@ -586,6 +690,7 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def change_description(job_name, description)
+        @logger.info "Changing the description of '#{job_name}' to '#{description}'"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         desc = n_xml.xpath("//description").first
@@ -601,6 +706,8 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def block_build_when_downstream_building(job_name)
+        @logger.info "Blocking builds of '#{job_name}' when downstream" +
+          " projects are building"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         node = n_xml.xpath("//blockBuildWhenDownstreamBuilding").first
@@ -618,6 +725,8 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def unblock_build_when_downstream_building(job_name)
+        @logger.info "Unblocking builds of '#{job_name}' when downstream" +
+          " projects are building"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         node = n_xml.xpath("//blockBuildWhenDownstreamBuilding").first
@@ -635,6 +744,8 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def block_build_when_upstream_building(job_name)
+        @logger.info "Blocking builds of '#{job_name}' when upstream" +
+          " projects are building"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         node = n_xml.xpath("//blockBuildWhenUpstreamBuilding").first
@@ -652,6 +763,8 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def unblock_build_when_upstream_building(job_name)
+        @logger.info "Unblocking builds of '#{job_name}' when upstream" +
+          " projects are building"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         node = n_xml.xpath("//blockBuildWhenUpstreamBuilding").first
@@ -670,6 +783,8 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def execute_concurrent_builds(job_name, option)
+        @logger.info "Setting the concurrent build execution option of" +
+          " '#{job_name}' to #{option}"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         node = n_xml.xpath("//concurrentBuild").first
@@ -688,6 +803,7 @@ module JenkinsApi
       # @return [Array] params_array Array of parameters for the given job
       #
       def get_build_params(job_name)
+        @logger.info "Obtaining the build params of '#{job_name}'"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         params = n_xml.xpath("//parameterDefinitions").first
@@ -791,13 +907,16 @@ module JenkinsApi
       # @param [String] job_name
       # @param [String] downstream_projects
       # @param [String] threshold - failure, success, or unstable
-      # @param [Bool] overwrite - true or false
+      # @param [Boolean] overwrite - true or false
       #
       # @return [String] response_code return code from HTTP POST
       #
       def add_downstream_projects(job_name,
                                   downstream_projects,
                                   threshold, overwrite = false)
+        @logger.info "Adding #{downstream_projects.inspect} as downstream" +
+          " projects for '#{job_name}' with the threshold of '#{threshold}'" +
+          " and overwrite option of '#{overwrite}'"
         name, ord, col = get_threshold_params(threshold)
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
@@ -836,6 +955,7 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def remove_downstream_projects(job_name)
+        @logger.info "Removing the downstream projects of '#{job_name}'"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         n_xml.search("//hudson.tasks.BuildTrigger").each do |node|
@@ -870,6 +990,7 @@ module JenkinsApi
       # @return [String] response_code return code from HTTP POST
       #
       def restrict_to_node(job_name, node_name)
+        @logger.info "Restricting '#{job_name}' to '#{node_name}' node"
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         if (node = n_xml.xpath("//assignedNode").first)
@@ -889,11 +1010,8 @@ module JenkinsApi
       # @param [Array] job_names Array of job names to be unchained
       #
       def unchain(job_names)
-        job_names.each do |job|
-          log_msg = "[INFO] Removing downstream projects for <#{job}>"
-          puts log_msg if @client.debug
-          remove_downstream_projects(job)
-        end
+        @logger.info "Unchaining jobs: #{job_names.inspect}"
+        job_names.each { |job| remove_downstream_projects(job) }
       end
 
       # Chain the jobs given based on specified criteria
@@ -911,12 +1029,13 @@ module JenkinsApi
         raise "Parallel jobs should be at least 1" if parallel < 1
         unchain(job_names)
 
+        @logger.info "Chaining jobs: #{job_names.inspect}" +
+          " with threshold of '#{threshold}' and criteria as '#{criteria}'" +
+          " with #{parallel} number of parallel jobs"
         filtered_job_names = []
         if criteria.include?("all") || criteria.empty?
           filtered_job_names = job_names
         else
-          log_msg = "[INFO] Criteria is specified. Filtering jobs..."
-          puts log_msg if @client.debug
           job_names.each do |job|
             filtered_job_names << job if criteria.include?(
               @client.job.get_current_build_status(job)
@@ -926,10 +1045,6 @@ module JenkinsApi
 
         filtered_job_names.each_with_index do |job_name, index|
           break if index >= (filtered_job_names.length - parallel)
-          msg = "[INFO] Adding <#{filtered_job_names[index+1]}> as a"
-          msg << " downstream project to <#{job_name}> with <#{threshold}> as"
-          msg << " the threshold"
-          puts msg if @client.debug
           @client.job.add_downstream_projects(
             job_name, filtered_job_names[index + parallel], threshold, true
           )