jenkins_api_client 0.14.1 → 1.0.0

data/lib/jenkins_api_client/job.rb

@@ -20,12 +20,18 @@
 # THE SOFTWARE.
 #
 
+require 'jenkins_api_client/urihelper'
+
 module JenkinsApi
   class Client
     # This class communicates with the Jenkins "/job" API to obtain details
     # about jobs, creating, deleting, building, and various other operations.
     #
     class Job
+      include JenkinsApi::UriHelper
+
+      # Version that jenkins started to include queued build info in build response
+      JENKINS_QUEUE_ID_SUPPORT_VERSION = '1.519'
 
       # Initialize the Job object and store the reference to Client object
       #
@@ -74,7 +80,7 @@ module JenkinsApi
       #
       def create(job_name, xml)
         @logger.info "Creating job '#{job_name}'"
-        @client.post_config("/createItem?name=#{job_name}", xml)
+        @client.post_config("/createItem?name=#{form_encode job_name}", xml)
       end
 
       # Update a job with the name specified and the xml given
@@ -197,7 +203,7 @@ module JenkinsApi
       # Update a job with params given as a hash instead of the xml. For the
       # parameter description see #create_or_update_freestyle
       #
-      # @param params [Hash]
+      # @param params [Hash] parameters to update a freestyle project
       #
       # @see #create_or_update_freestyle
       # @see #update
@@ -334,7 +340,7 @@ module JenkinsApi
       # @option params [String] :name Name of the job
       # @option params [String] :notification_email Email address to send
       # @option params [Boolean] :notification_email_for_every_unstable
-      # Send email notification email for every unstable build
+      #   Send email notification email for every unstable build
       #
       def add_email_notification(params)
         raise "No job name specified" unless params[:name]
@@ -400,16 +406,18 @@ module JenkinsApi
       #
       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}")
+        @client.api_post_request("/job/#{path_encode old_job}/doRename?newName=#{form_encode new_job}")
       end
 
       # Delete a job given the name
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to delete
+      #
+      # @return [String] the response from the HTTP POST request
       #
       def delete(job_name)
         @logger.info "Deleting job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/doDelete")
+        @client.api_post_request("/job/#{path_encode job_name}/doDelete")
       end
 
       # Deletes all jobs from Jenkins
@@ -424,11 +432,13 @@ module JenkinsApi
 
       # Wipe out the workspace for a job given the name
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to wipe out the workspace
+      #
+      # @return [String] response from the HTTP POST request
       #
       def wipe_out_workspace(job_name)
         @logger.info "Wiping out the workspace of job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/doWipeOutWorkspace")
+        @client.api_post_request("/job/#{path_encode job_name}/doWipeOutWorkspace")
       end
 
       # Stops a running build of a job
@@ -436,8 +446,8 @@ module JenkinsApi
       # is specified. The build will be stopped only if it was
       # in 'running' state.
       #
-      # @param [String] job_name
-      # @param [Number] build_number
+      # @param job_name [String] the name of the job to stop the build
+      # @param build_number [Number] the build number to stop
       #
       def stop_build(job_name, build_number = 0)
         build_number = get_current_build_number(job_name) if build_number == 0
@@ -445,17 +455,21 @@ module JenkinsApi
         @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}"
+          "/job/#{path_encode job_name}/#{build_number}"
         )["building"]
         if is_building
-          @client.api_post_request("/job/#{job_name}/#{build_number}/stop")
+          @client.api_post_request("/job/#{path_encode job_name}/#{build_number}/stop")
         end
       end
+      alias_method :stop, :stop_build
+      alias_method :abort, :stop_build
 
       # Re-create the same job
       # This is a hack to clear any existing builds
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to recreate
+      #
+      # @return [String] the response from the HTTP POST request
       #
       def recreate(job_name)
         @logger.info "Recreating job '#{job_name}'"
@@ -466,14 +480,16 @@ module JenkinsApi
 
       # Copy a job
       #
-      # @param [String] from_job_name
-      # @param [String] to_job_name
+      # @param from_job_name [String] the name of the job to copy from
+      # @param to_job_name [String] the name of the job to copy to
+      #
+      # @return [String] the response from the HTTP POST request
       #
       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}"
+          "/createItem?name=#{path_encode to_job_name}&mode=copy&from=#{path_encode from_job_name}"
         )
       end
 
@@ -481,7 +497,7 @@ module JenkinsApi
       #
       # @param [String] job_name Name of the Jenkins job
       # @param [Number] build_num Specific build number to obtain the
-      #                 console output from. Default is the recent build
+      #   console output from. Default is the recent build
       # @param [Number] start start offset to get only a portion of the text
       # @param [String] mode Mode of text output. 'text' or 'html'
       #
@@ -505,7 +521,7 @@ module JenkinsApi
         else
           raise "Mode should either be 'text' or 'html'. You gave: #{mode}"
         end
-        get_msg = "/job/#{job_name}/#{build_num}/logText/progressive#{mode}?"
+        get_msg = "/job/#{path_encode job_name}/#{build_num}/logText/progressive#{mode}?"
         get_msg << "start=#{start}"
         raw_response = true
         api_response = @client.api_get_request(get_msg, nil, nil, raw_response)
@@ -520,6 +536,8 @@ module JenkinsApi
 
       # List all jobs on the Jenkins CI server
       #
+      # @return [Array<String>] the names of all jobs in jenkins
+      #
       def list_all
         response_json = @client.api_get_request("", "tree=jobs[name]")["jobs"]
         response_json.map { |job| job["name"] }.sort
@@ -527,7 +545,9 @@ module JenkinsApi
 
       # Checks if the given job exists in Jenkins
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to check
+      #
+      # @return [Boolean] whether the job exists in jenkins or not
       #
       def exists?(job_name)
         list(job_name).include?(job_name)
@@ -536,8 +556,12 @@ module JenkinsApi
       # List all Jobs matching the given status
       # You can optionally pass in jobs list to filter the status from
       #
-      # @param [String] status
-      # @param [Array] jobs
+      # @param status [String] the job status to filter
+      # @param jobs [Array<String>] if specified this array will be used for
+      #   filtering by the status otherwise the filtering will be done using
+      #   all jobs available in jenkins
+      #
+      # @return [Array<String>] filtered jobs
       #
       def list_by_status(status, jobs = [])
         jobs = list_all if jobs.empty?
@@ -555,8 +579,10 @@ module JenkinsApi
 
       # List all jobs that match the given regex
       #
-      # @param [String] filter - a regex
-      # @param [Boolean] ignorecase
+      # @param filter [String] a regular expression or a string to filter jobs
+      # @param ignorecase [Boolean] whether to ignore case or not
+      #
+      # @return [Array<String>] jobs matching the given pattern
       #
       def list(filter, ignorecase = true)
         @logger.info "Obtaining jobs matching filter '#{filter}'"
@@ -574,6 +600,8 @@ module JenkinsApi
 
       # List all jobs on the Jenkins CI server along with their details
       #
+      # @return [Array<Hash>] the details of all jobs in jenkins
+      #
       def list_all_with_details
         @logger.info "Obtaining the details of all jobs"
         response_json = @client.api_get_request("")
@@ -582,30 +610,34 @@ module JenkinsApi
 
       # List details of a specific job
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to obtain the details from
+      #
+      # @return [Hash] the details of the specified job
       #
       def list_details(job_name)
         @logger.info "Obtaining the details of '#{job_name}'"
-        @client.api_get_request("/job/#{job_name}")
+        @client.api_get_request("/job/#{path_encode job_name}")
       end
 
       # List upstream projects of a specific job
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to obtain upstream
+      #  projects for
       #
       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 = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["upstreamProjects"]
       end
 
       # List downstream projects of a specific job
       #
-      # @param [String] job_name
+      # @param job_name [String] the name of the job to obtain downstream
+      #   projects for
       #
       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 = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["downstreamProjects"]
       end
 
@@ -615,7 +647,7 @@ module JenkinsApi
       #
       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 = @client.api_get_request("/job/#{path_encode job_name}")
         response_json["builds"]
       end
 
@@ -657,9 +689,10 @@ module JenkinsApi
       #
       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}")
+        response_json = @client.api_get_request("/job/#{path_encode job_name}")
         color_to_status(response_json["color"])
       end
+      alias_method :status, :get_current_build_status
 
       # Obtain the current build number of the given job
       # This function returns nil if there were no builds for the given job.
@@ -670,60 +703,248 @@ module JenkinsApi
       #
       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
+        @client.api_get_request("/job/#{path_encode 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
+      alias_method :build_number, :get_current_build_number
+
+      # Build a Jenkins job, optionally waiting for build to start and
+      # returning the build number.
+      # Adds support for new/old Jenkins servers where build_queue id may
+      # not be available. Also adds support for periodic callbacks, and
+      # optional cancellation of queued_job if not started within allowable
+      # time window (if build_queue option available)
+      #
+      #   Notes:
+      #     'opts' may be a 'true' or 'false' value to maintain
+      #       compatibility with old method signature, where true indicates
+      #     'return_build_number'. In this case, true is translated to:
+      #       { 'build_start_timeout' => @client_timeout }
+      #       which simulates earlier behavior.
+      #
+      #   progress_proc
+      #     Optional proc that is called periodically while waiting for
+      #     build to start.
+      #     Initial call (with poll_count == 0) indicates build has been
+      #     requested, and that polling is starting.
+      #     Final call will indicate one of build_started or cancelled.
+      #     params:
+      #       max_wait [Integer] Same as opts['build_start_timeout']
+      #       current_wait [Integer]
+      #       poll_count [Integer] How many times has queue been polled
+      #
+      #   completion_proc
+      #     Optional proc that is called <just before> the 'build' method
+      #     exits.
+      #     params:
+      #       build_number [Integer]  Present if build started or nil
+      #       build_cancelled [Boolean]  True if build timed out and was
+      #         successfully removed from build-queue
       #
       # @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)
+      # @param [Hash]   params   the parameters for parameterized build
+      # @param [Hash]   opts     options for this method
+      #  * +build_start_timeout+ [Integer] How long to wait for queued
+      #    build to start before giving up. Default: 0/nil
+      #  * +cancel_on_build_start_timeout+ [Boolean] Should an attempt be
+      #    made to cancel the queued build if it hasn't started within
+      #    'build_start_timeout' seconds? This only works on newer versions
+      #    of Jenkins where JobQueue is exposed in build post response.
+      #    Default: false
+      #  * +poll_interval+ [Integer] How often should we check with CI
+      #    Server while waiting for start. Default: 2 (seconds)
+      #  * +progress_proc+ [Proc] A proc that will receive progress notitications. Default: nil
+      #  * +completion_proc+ [Proc] A proc that is called <just before>
+      #    this method (build) exits.  Default: nil
+      #
+      # @return [Integer] build number, or nil if not started (IF TIMEOUT SPECIFIED)
+      # @return [Integer] HTTP response code (per prev. behavior) (NO TIMEOUT SPECIFIED)
+      #
+      def build(job_name, params={}, opts = {})
+        if opts.nil? || opts.class.is_a?(FalseClass)
+          opts = {}
+        elsif opts.class.is_a?(TrueClass)
+          opts = { 'build_start_timeout' => @client_timeout }
+        end
+
+        opts['job_name'] = job_name
+
         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
+
+        # Best-guess build-id
+        # This is only used if we go the old-way below... but we can use this number to detect if multiple
+        # builds were queued
+        current_build_id = get_current_build_number(job_name)
+        expected_build_id = current_build_id > 0 ? current_build_id + 1 : 1
+
+        if (params.nil? or params.empty?)
+          response = @client.api_post_request("/job/#{path_encode job_name}/build",
+            {},
+            true)
+        else
+          response = @client.api_post_request("/job/#{path_encode job_name}/buildWithParameters",
+            params,
+            true)
+        end
+
+        if (opts['build_start_timeout'] || 0) > 0
+          if @client.compare_versions(@client.get_jenkins_version, JENKINS_QUEUE_ID_SUPPORT_VERSION) >= 0
+            return get_build_id_from_queue(response, expected_build_id, opts)
+          else
+            return get_build_id_the_old_way(expected_build_id, opts)
+          end
+        else
+          return response.code
+        end
+      end
+
+      def get_build_id_from_queue(response, expected_build_id, opts)
+        # If we get this far the API hasn't detected an error response (it would raise Exception)
+        # So no need to check response code
+        # 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
+        build_start_timeout = opts['build_start_timeout']
+        poll_interval = opts['poll_interval'] || 2
+        poll_interval = 1 if poll_interval < 1
+        progress_proc = opts['progress_proc']
+        completion_proc = opts['completion_proc']
+        job_name = opts['job_name']
+
+        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.info "Job queued for #{job_name}, will wait up to #{build_start_timeout} seconds for build to start..."
+
+            # Let progress proc know we've queued the build
+            progress_proc.call(build_start_timeout, 0, 0) if progress_proc
+
+            # Wait for the build to start
+            begin
+              start = Time.now.to_i
+              Timeout::timeout(build_start_timeout) do
+                started = false
+                attempts = 0
+
+                while !started
+                  # Don't really care about the response... if we get thru here, then it must have worked.
+                  # Jenkins will return 404's until the job starts
+                  queue_item = @client.queue.get_item_by_id(task_id)
+
+                  if queue_item['executable'].nil?
+                    # Job not started yet
+                    attempts += 1
+
+                    progress_proc.call(build_start_timeout, (Time.now.to_i - start), attempts) if progress_proc
+                    # Every 5 attempts (~10 seconds)
+                    @logger.info "Still waiting..." if attempts % 5 == 0
+
+                    sleep poll_interval
+                  else
+                    build_number = queue_item['executable']['number']
+                    completion_proc.call(build_number, false) if completion_proc
+
+                    return build_number
+                  end
                 end
               end
-              @client.queue.get_item_by_id(task_id)["executable"]["number"]
-            else
-              nil
+            rescue Timeout::Error
+              # Well, we waited - and the job never started building
+              # Attempt to kill off queued job (if flag set)
+              if opts['cancel_on_build_start_timeout']
+                @logger.info "Job for '#{job_name}' did not start in a timely manner, attempting to cancel pending build..."
+
+                begin
+                  @client.api_post_request("/queue/cancelItem?id=#{task_id}")
+                  @logger.info "Job cancelled"
+                  completion_proc.call(nil, true) if completion_proc
+                rescue JenkinsApi::Exceptions::ApiException => e
+                  completion_proc.call(nil, false) if completion_proc
+                  @logger.warn "Error while attempting to cancel pending job for '#{job_name}'. #{e.class} #{e}"
+                  raise
+                end
+              else
+                @logger.info "Jenkins build for '#{job_name}' failed to start in a timely manner"
+                completion_proc.call(nil, false) if completion_proc
+              end
+
+              # Old version used to throw timeout error, so we should let that go thru now
+              raise
+            rescue JenkinsApi::Exceptions::ApiException => e
+              # Jenkins Api threw an error at us
+              completion_proc.call(nil, false) if completion_proc
+              @logger.warn "Problem while waiting for '#{job_name}' build to start.  #{e.class} #{e}"
+              raise
             end
           else
-            nil
+            @logger.warn "Jenkins did not return a queue_id for '#{job_name}' build (location: #{response['location']})"
+            return get_build_id_the_old_way(expected_build_id, opts)
           end
         else
-          response
+          @logger.warn "Jenkins did not return a location header for '#{job_name}' build"
+          return get_build_id_the_old_way(expected_build_id, opts)
+        end
+      end
+      private :get_build_id_from_queue
+
+      def get_build_id_the_old_way(expected_build_id, opts)
+        # Try to wait until the build starts so we can mimic queue
+        # Wait for the build to start
+        build_start_timeout = opts['build_start_timeout']
+        poll_interval = opts['poll_interval'] || 2
+        poll_interval = 1 if poll_interval < 1
+        progress_proc = opts['progress_proc']
+        completion_proc = opts['completion_proc']
+        job_name = opts['job_name']
+
+        @logger.info "Build requested for '#{job_name}', will wait up to #{build_start_timeout} seconds for build to start..."
+
+        # Let progress proc know we've queued the build
+        progress_proc.call(build_start_timeout, 0, 0) if progress_proc
+
+        begin
+          start = Time.now.to_i
+          Timeout::timeout(build_start_timeout) do
+            attempts = 0
+
+            while true
+              attempts += 1
+
+              # Don't really care about the response... if we get thru here, then it must have worked.
+              # Jenkins will return 404's until the job starts
+              begin
+                get_build_details(job_name, expected_build_id)
+                completion_proc.call(expected_build_id, false) if completion_proc
+
+                return expected_build_id
+              rescue JenkinsApi::Exceptions::NotFound => e
+                progress_proc.call(build_start_timeout, (Time.now.to_i - start), attempts) if progress_proc
+
+                # Every 5 attempts (~10 seconds)
+                @logger.info "Still waiting..." if attempts % 5 == 0
+
+                sleep poll_interval
+              end
+            end
+          end
+        rescue Timeout::Error
+          # Well, we waited - and the job never started building
+          # Now we need to raise an exception so that the build can be officially failed
+          completion_proc.call(nil, false) if completion_proc
+          @logger.info "Jenkins '#{job_name}' build failed to start in a timely manner"
+
+          # Old version used to propagate timeout error
+          raise
+        rescue JenkinsApi::Exceptions::ApiException => e
+          completion_proc.call(nil, false) if completion_proc
+          # Jenkins Api threw an error at us
+          @logger.warn "Problem while waiting for '#{job_name}' build ##{expected_build_id} to start.  #{e.class} #{e}"
+          raise
         end
       end
+      private :get_build_id_the_old_way
 
       # Programatically schedule SCM polling for the specified job
       #
@@ -742,7 +963,7 @@ module JenkinsApi
       #
       def enable(job_name)
         @logger.info "Enabling job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/enable")
+        @client.api_post_request("/job/#{path_encode job_name}/enable")
       end
 
       # Disable a job given the name of the job
@@ -751,7 +972,7 @@ module JenkinsApi
       #
       def disable(job_name)
         @logger.info "Disabling job '#{job_name}'"
-        @client.api_post_request("/job/#{job_name}/disable")
+        @client.api_post_request("/job/#{path_encode job_name}/disable")
       end
 
       # Obtain the configuration stored in config.xml of a specific job
@@ -762,7 +983,7 @@ module JenkinsApi
       #
       def get_config(job_name)
         @logger.info "Obtaining the config.xml of '#{job_name}'"
-        @client.get_config("/job/#{job_name}")
+        @client.get_config("/job/#{path_encode job_name}")
       end
 
       # Post the configuration of a job given the job name and the config.xml
@@ -774,7 +995,7 @@ module JenkinsApi
       #
       def post_config(job_name, xml)
         @logger.info "Posting the config.xml of '#{job_name}'"
-        @client.post_config("/job/#{job_name}/config.xml", xml)
+        @client.post_config("/job/#{path_encode job_name}/config.xml", xml)
       end
 
       # Obtain the test results for a specific build of a job
@@ -786,7 +1007,7 @@ module JenkinsApi
         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")
+        @client.api_get_request("/job/#{path_encode job_name}/#{build_num}/testReport")
       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
@@ -803,7 +1024,7 @@ module JenkinsApi
         @logger.info "Obtaining the build details of '#{job_name}'" +
           " Build ##{build_num}"
 
-        @client.api_get_request("/job/#{job_name}/#{build_num}/")
+        @client.api_get_request("/job/#{path_encode job_name}/#{build_num}/")
       end
 
       # Change the description of a specific job
@@ -1179,6 +1400,31 @@ module JenkinsApi
         filtered_job_names[0..parallel-1]
       end
 
+      # Get a list of promoted builds for given job
+      #
+      # @param  [String] job_name
+      # @return [Hash]   Hash map of promitions and the promoted builds. Promotions that didn't took place yet
+      #                  return nil
+      def get_promotions(job_name)
+        result = {}
+
+        @logger.info "Obtaining the promotions of '#{job_name}'"
+        response_json = @client.api_get_request("/job/#{job_name}/promotion")
+
+        response_json["processes"].each do |promotion|
+          @logger.info "Getting promotion details of '#{promotion['name']}'"
+
+          if promotion['color'] == 'notbuilt'
+            result[promotion['name']] = nil
+          else
+            promo_json = @client.api_get_request("/job/#{job_name}/promotion/latest/#{promotion['name']}")
+            result[promotion['name']] = promo_json['target']['number']
+          end
+        end
+
+        result
+      end
+
       private
 
       # Obtains the threshold params used by jenkins in the XML file