jenkins_api_client 0.0.1 → 0.0.2

data/README.rdoc

@@ -0,0 +1,14 @@
+= jenkins_api_client
+
+Client libraries for communicating with a Jenkins CI server
+
+== Sample Usage:
+
+Install jenkins_api_client by <tt>sudo gem install jenkins_api_client</tt>
+
+  require 'jenkins_api_client'
+
+  client = JenkinsApi::Client.new(:server_ip => '0.0.0.0', 
+           :username => 'somename', :password => 'secret password')
+  # The following call will return all jobs matching 'Testjob'
+  puts client.job.list("^Testjob")

data/lib/jenkins_api_client/client.rb

@@ -12,11 +12,17 @@ require File.expand_path('../job', __FILE__)
 module JenkinsApi
   class Client
 
-    attr_accessor :server_ip, :server_port, :username, :password
     DEFAULT_SERVER_PORT = 8080
     VALID_PARAMS = %w(server_ip server_port username password)
 
+    # Initialize a Client object with Jenkins CI server information and credentials
+    #
     # @param [Hash] args
+    #  * the +:server_ip+ param is the IP address of the Jenkins CI server
+    #  * the +:server_port+ param is the port on which the Jenkins server listens
+    #  * the +:username+ param is the username used for connecting to the CI server
+    #  * the +:password+ param is the password for connecting to the CI server
+    #
     def initialize(args)
       args.each { |key, value|
         instance_variable_set("@#{key}", value) if value
@@ -26,14 +32,22 @@ module JenkinsApi
      @server_port = DEFAULT_SERVER_PORT unless @server_port
     end
 
+    # Creates an instance to the Job object by passing a reference to self
+    #
     def job
       JenkinsApi::Client::Job.new(self)
     end
 
+    # Returns a string representing the class name
+    #
     def to_s
       "#<JenkinsApi::Client>"
     end
 
+    # Sends a GET request to the Jenkins CI server with the specified URL
+    #
+    # @param [String] url_prefix
+    #
     def api_get_request(url_prefix)
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Get.new("#{url_prefix}/api/json")
@@ -42,6 +56,10 @@ module JenkinsApi
       JSON.parse(response.body)
     end
 
+    # Sends a POST message to the Jenkins CI server with the specified URL
+    #
+    # @param [String] url_prefix
+    #
     def api_post_request(url_prefix)
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Post.new("#{url_prefix}")
@@ -49,7 +67,10 @@ module JenkinsApi
       response = http.request(request)
     end
 
-
+    # Obtains the configuration of a component from the Jenkins CI server
+    #
+    # @param [String] url_prefix
+    #
     def get_config(url_prefix)
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Get.new("#{url_prefix}/config.xml")
@@ -58,6 +79,11 @@ module JenkinsApi
       response.body
     end
 
+    # Posts the given xml configuration to the url given
+    #
+    # @param [String] url_prefix
+    # @param [String] xml
+    #
     def post_config(url_prefix, xml)
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Post.new("#{url_prefix}/config.xml")

data/lib/jenkins_api_client/job.rb

@@ -2,14 +2,14 @@ module JenkinsApi
   class Client
     class Job
 
+      # Initialize the Job object and store the reference to Client object
+      #
       def initialize(client)
         @client = client
       end
 
-      def test_method
-        puts "Username is: #{@client}"
-      end
-
+      # List all jobs on the Jenkins CI server
+      #
       def list_all
         response_json = @client.api_get_request("")
         jobs = []
@@ -19,6 +19,10 @@ module JenkinsApi
         jobs.sort!
       end
 
+      # List all jobs that match the given regex
+      #
+      # @param [String] filter - a regex
+      #
       def list(filter)
         response_json = @client.api_get_request("")
         jobs = []
@@ -28,52 +32,130 @@ module JenkinsApi
         jobs
       end
 
+      # 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"]
       end
 
+      # List details of a specific job
+      #
+      # @param [String] job_name
+      #
       def list_details(job_name)
         @client.api_get_request("/job/#{job_name}")
       end
 
+      # List upstream projects of a specific job
+      #
+      # @param [String] job_name
+      #
       def get_upstream_projects(job_name)
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["upstreamProjects"]
       end
 
+      # List downstream projects of a specific job
+      #
+      # @param [String] job_name
+      #
       def get_downstream_projects(job_name)
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["downstreamProjects"]
       end
 
+      # Obtain build details of a specific job
+      #
+      # @param [String] job_name
+      #
       def get_builds(job_name)
         response_json = @client.api_get_request("/job/#{job_name}")
         response_json["builds"]
       end
 
+      # Obtain the current build status of the job
+      # By defaule Jenkins returns the color of the job status icon
+      # This function translates the color into a meaningful status
+      #
+      # @param [String] job_name
+      #
+      def get_current_build_status(job_name)
+        response_json = @client.api_get_request("/job/#{job_name}")
+        case response_json["color"]
+        when "blue"
+          "success"
+        when "red"
+          "failure"
+        when "yellow"
+          "unstable"
+        when "grey_anime", "blue_anime", "red_anime"
+          "running"
+        when "grey"
+          "not run"
+        when "aborted"
+          "aborted"
+        end
+      end
+
+      # This functions lists all jobs that are currently running on the Jenkins CI server
+      #
+      def list_running
+        jobs = list_all
+        running_jobs = []
+        jobs.each { |job|
+          running_jobs << job if get_current_build_status(job) == "running"
+        }
+        running_jobs
+      end
+
+      # Build a job given the name of the job
+      #
+      # @param [String] job_name
+      #
       def build(job_name)
         @client.api_post_request("/job/#{job_name}/build")
       end
 
+      # Obtain the configuration stored in config.xml of a specific job
+      #
+      # @param [String] job_name
+      #
       def get_config(job_name)
         @client.get_config("/job/#{job_name}")
       end
 
+      # Post the configuration of a job given the job name and the config.xml
+      #
+      # @param [String] job_name
+      # @param [String] xml
+      #
       def post_config(job_name, xml)
         @client.post_config("/job/#{job_name}", xml)
       end
 
-      def change_description(job_name)
+      # Change the description of a specific job
+      #
+      # @param [String] job_name
+      # @param [String] description
+      #
+      def change_description(job_name, description)
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
         desc = n_xml.xpath("//description").first
-        desc.content = "Some description"
+        desc.content = "#{description}"
         xml_modified = n_xml.to_xml
         post_config(job_name, xml_modified)
       end
 
-      def add_downstream_projects(job_name, downstream_project, threshold = 'success')
+      # Add downstream projects to a specific job given the job name, projects to be
+      # added as downstream projects, and the threshold
+      #
+      # @param [String] job_name
+      # @param [String] downstream_projects
+      # @param [String] threshold - failure, success, or unstable
+      #
+      def add_downstream_projects(job_name, downstream_projects, threshold = 'success')
         case threshold
         when 'success'
           name = 'SUCCESS'
@@ -92,11 +174,11 @@ module JenkinsApi
         n_xml = Nokogiri::XML(xml)
         child_projects_node = n_xml.xpath("//childProjects").first
         if child_projects_node
-          child_projects_node.content = child_projects_node.content + ", #{downstream_project}"
+          child_projects_node.content = child_projects_node.content + ", #{downstream_projects}"
         else
           publisher_node = n_xml.xpath("//publishers").first
           build_trigger_node = publisher_node.add_child("<hudson.tasks.BuildTrigger/>")
-          child_project_node = build_trigger_node.first.add_child("<childProjects>#{downstream_project}</childProjects>")
+          child_project_node = build_trigger_node.first.add_child("<childProjects>#{downstream_projects}</childProjects>")
           threshold_node = child_project_node.first.add_next_sibling("<threshold/>")
           threshold_node.first.add_child("<name>#{name}</name><ordinal>#{ordinal}</ordinal><color>#{color}</color>")
         end
@@ -104,6 +186,10 @@ module JenkinsApi
         post_config(job_name, xml_modified)
       end
 
+      # Remove all downstream projects of a specific job
+      #
+      # @param [String] job_name
+      #
       def remove_downstream_projects(job_name)
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)
@@ -131,6 +217,11 @@ module JenkinsApi
         post_config(job_name, xml_modified)
       end
 
+      # Resctrict the given job to a specific node
+      #
+      # @param [String] job_name
+      # @param [String] node_name
+      #
       def restrict_to_node(job_name, node_name)
         xml = get_config(job_name)
         n_xml = Nokogiri::XML(xml)

data/lib/jenkins_api_client/version.rb

@@ -1,6 +1,6 @@
 
 module JenkinsApi
   class Client
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jenkins_api_client
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-15 00:00:00.000000000 Z
+date: 2012-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -165,10 +165,10 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
+- README.rdoc
 files:
 - Gemfile
-- README.md
+- README.rdoc
 - Rakefile
 - lib/jenkins_api_client.rb
 - lib/jenkins_api_client/client.rb
@@ -189,7 +189,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -29913673152348123
+      hash: -746284255980224518
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/README.md

@@ -1,4 +0,0 @@
-jenkins_api_client
-==================
-
-Client libraries for communicating with a Jenkins CI server