jira-ruby 0.0.4 → 0.1.0

data/README.rdoc

@@ -5,7 +5,7 @@ API version 2).
 
 == Example usage
 
-  client = JIRA::Client.new(CONSUMER_KEY, CONSUMER_SECRET)
+  client = JIRA::Client.new({:consumer_key => CONSUMER_KEY, :consumer_secret => CONSUMER_SECRET})
 
   project = client.Project.find('SAMPLEPROJECT')
 
@@ -70,9 +70,47 @@ key.
   After you have entered all the information click OK and ensure OAuth authentication is
   enabled.
 
+== Configuring JIRA to use HTTP Basic Auth
+
+Follow the same steps described above to set up a new Application Link in JIRA,
+however there is no need to set up any "incoming authentication" as this
+defaults to HTTP Basic Auth.
+
+== Using the API Gem in a command line application
+
+Using HTTP Basic Authentication, configure and connect a client to your instance
+of JIRA.
+
+  require 'rubygems'
+  require 'pp'
+  require 'jira'
+
+  # Consider the use of :use_ssl and :ssl_verify_mode options if running locally 
+  # for tests.
+
+  username = "myremoteuser"
+  password = "myuserspassword"
+
+  options = {
+              :username => username,
+              :password => password,
+              :site     => 'http://localhost:8080/',
+              :context_path => '/myjira',
+              :auth_type => :basic
+            }
+
+  client = JIRA::Client.new(options)
+
+  # Show all projects
+  projects = client.Project.all
+  
+  projects.each do |project|
+    puts "Project -> key: #{project.key}, name: #{project.name}"
+  end
+
 == Using the API Gem in your Rails application
 
-The gem requires the consumer key and public certificate file (which
+Using oauth, the gem requires the consumer key and public certificate file (which
 are generated in their respective rake tasks) to initialize an access token for
 using the JIRA API.
 
@@ -95,17 +133,22 @@ errors are handled gracefully
   class ApplicationController < ActionController::Base
     protect_from_forgery
 
-    rescue_from JIRA::Client::UninitializedAccessTokenError do
+    rescue_from JIRA::OauthClient::UninitializedAccessTokenError do
       redirect_to new_jira_session_url
     end
 
     private
 
     def get_jira_client
+      
+      # add any extra configuration options for your instance of JIRA,
+      # e.g. :use_ssl, :ssl_verify_mode, :context_path, :site
       options = {
-        :private_key_file => "rsakey.pem"
+        :private_key_file => "rsakey.pem",
+        :consumer_key => 'test'
       }
-      @jira_client = JIRA::Client.new('test', '', options)
+
+      @jira_client = JIRA::Client.new(options)
 
       # Add AccessToken if authorised previously.
       if session[:jira_auth]
@@ -190,10 +233,11 @@ Here's the same example as a Sinatra application:
         :authorize_path     => "/plugins/servlet/oauth/authorize",
         :access_token_path  => "/plugins/servlet/oauth/access-token",
         :private_key_file   => "rsakey.pem",
-        :rest_base_path     => "/rest/api/2"
+        :rest_base_path     => "/rest/api/2",
+        :consumer_key       => "jira-ruby-example"
       }
 
-      @jira_client = JIRA::Client.new('jira-ruby-example', '', options)
+      @jira_client = JIRA::Client.new(options)
       @jira_client.consumer.http.set_debug_output($stderr)
 
       # Add AccessToken if authorised previously.

data/http-basic-example.rb

@@ -0,0 +1,106 @@
+require 'rubygems'
+require 'pp'
+require 'jira'
+
+if ARGV.length == 0
+  # If not passed any command line arguments, prompt the
+  # user for the username and password.
+  puts "Enter the username: "
+  username = gets.strip
+
+  puts "Enter the password: "
+  password = gets.strip
+elsif ARGV.length == 2
+  username, password = ARGV[0], ARGV[1]
+else
+  # Script must be passed 0 or 2 arguments
+  raise "Usage: #{$0} [ username password ]"
+end
+
+options = {
+            :username => username,
+            :password => password,
+            :site     => 'http://localhost:8080/',
+            :context_path => '',
+            :auth_type => :basic,
+            :use_ssl => false
+          }
+
+client = JIRA::Client.new(options)
+
+# Show all projects
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
+end
+
+# # Find a specific project by key
+# # ------------------------------
+# project = client.Project.find('SAMPLEPROJECT')
+# pp project
+# project.issues.each do |issue|
+#   puts "#{issue.id} - #{issue.fields['summary']}"
+# end
+#
+# # List all Issues
+# # ---------------
+# client.Issue.all.each do |issue|
+#   puts "#{issue.id} - #{issue.fields['summary']}"
+# end
+#
+# # Delete an issue
+# # ---------------
+# issue = client.Issue.find('SAMPLEPROJECT-2')
+# if issue.delete
+#   puts "Delete of issue SAMPLEPROJECT-2 sucessful"
+# else
+#   puts "Delete of issue SAMPLEPROJECT-2 failed"
+# end
+#
+# # Create an issue
+# # ---------------
+# issue = client.Issue.build
+# issue.save({"fields"=>{"summary"=>"blarg from in example.rb","project"=>{"id"=>"10001"},"issuetype"=>{"id"=>"3"}}})
+# issue.fetch
+# pp issue
+#
+# # Update an issue
+# # ---------------
+# issue = client.Issue.find("10002")
+# issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})
+# pp issue
+#
+# # Find a user
+# # -----------
+# user = client.User.find('admin')
+# pp user
+#
+# # Get all issue types
+# # -------------------
+# issuetypes = client.Issuetype.all
+# pp issuetypes
+#
+# # Get a single issue type
+# # -----------------------
+# issuetype = client.Issuetype.find('5')
+# pp issuetype
+#
+# #  Get all comments for an issue
+# #  -----------------------------
+# issue.comments.each do |comment|
+#   pp comment
+# end
+#
+# # Build and Save a comment
+# # ------------------------
+# comment = issue.comments.build
+# comment.save!(:body => "New comment from example script")
+#
+# # Delete a comment from the collection
+# # ------------------------------------
+# issue.comments.last.delete
+#
+# # Update an existing comment
+# # --------------------------
+# issue.comments.first.save({"body" => "an updated comment frome example.rb"})

data/lib/jira.rb

@@ -22,6 +22,9 @@ require 'jira/resource/comment'
 require 'jira/resource/worklog'
 require 'jira/resource/issue'
 
+require 'jira/request_client'
+require 'jira/oauth_client'
+require 'jira/http_client'
 require 'jira/client'
 
 require 'jira/railtie' if defined?(Rails)

data/lib/jira/client.rb

@@ -1,4 +1,3 @@
-require 'oauth'
 require 'json'
 require 'forwardable'
 
@@ -6,9 +5,8 @@ module JIRA
 
   # This class is the main access point for all JIRA::Resource instances.
   #
-  # The client must be initialized with a consumer_key and consumer secret,
-  # and an optional hash of extra configuration options.  The available options
-  # are:
+  # The client must be initialized with an options hash containing 
+  # configuration options.  The available options are:
   #
   #   :site               => 'http://localhost:2990',
   #   :context_path       => '/jira',
@@ -17,55 +15,56 @@ module JIRA
   #   :authorize_path     => "/plugins/servlet/oauth/authorize",
   #   :access_token_path  => "/plugins/servlet/oauth/access-token",
   #   :private_key_file   => "rsakey.pem",
-  #   :rest_base_path     => "/rest/api/2"
-  #
+  #   :rest_base_path     => "/rest/api/2",
+  #   :consumer_key       => nil,
+  #   :consumer_secret    => nil,
+  #   :ssl_verify_mode    => OpenSSL::SSL::VERIFY_PEER,
+  #   :use_ssl            => true,
+  #   :username           => nil,
+  #   :password           => nil,
+  #   :auth_type          => :oauth
   #
   # See the JIRA::Base class methods for all of the available methods on these accessor
   # objects.
-  #
+  
   class Client
 
     extend Forwardable
 
-    # This exception is thrown when the client is used before the OAuth access token
-    # has been initialized.
-    class UninitializedAccessTokenError < StandardError
-      def message
-        "init_access_token must be called before using the client"
-      end
-    end
-
-    # The OAuth::Consumer instance used by this client
-    attr_accessor :consumer
+    # The OAuth::Consumer instance returned by the OauthClient
+    #
+    # The authenticated client instance returned by the respective client type
+    # (Oauth, Basic)
+    attr_accessor :consumer, :request_client
 
     # The configuration options for this client instance
     attr_reader :options
 
-    def_instance_delegators :@consumer, :key, :secret, :get_request_token
+    def_delegators :@request_client, :init_access_token, :set_access_token, :set_request_token, :request_token, :access_token
 
     DEFAULT_OPTIONS = {
       :site               => 'http://localhost:2990',
       :context_path       => '/jira',
-      :signature_method   => 'RSA-SHA1',
-      :request_token_path => "/plugins/servlet/oauth/request-token",
-      :authorize_path     => "/plugins/servlet/oauth/authorize",
-      :access_token_path  => "/plugins/servlet/oauth/access-token",
-      :private_key_file   => "rsakey.pem",
-      :rest_base_path     => "/rest/api/2"
+      :rest_base_path     => "/rest/api/2",
+      :ssl_verify_mode    => OpenSSL::SSL::VERIFY_PEER,
+      :use_ssl            => true,
+      :auth_type          => :oauth
     }
 
-    def initialize(consumer_key, consumer_secret, options={})
+    def initialize(options={})
       options = DEFAULT_OPTIONS.merge(options)
-
-      # prepend the context path to all authorization and rest paths
-      options[:request_token_path] = options[:context_path] + options[:request_token_path]
-      options[:authorize_path] = options[:context_path] + options[:authorize_path]
-      options[:access_token_path] = options[:context_path] + options[:access_token_path]
-      options[:rest_base_path] = options[:context_path] + options[:rest_base_path]
-
       @options = options
+      @options[:rest_base_path] = @options[:context_path] + @options[:rest_base_path]
+
+      case options[:auth_type]
+      when :oauth
+        @request_client = OauthClient.new(@options)
+        @consumer = @request_client.consumer
+      when :basic
+        @request_client = HttpClient.new(@options)
+      end
+
       @options.freeze
-      @consumer = OAuth::Consumer.new(consumer_key,consumer_secret,options)
     end
 
     def Project # :nodoc:
@@ -112,44 +111,17 @@ module JIRA
       JIRA::Resource::VersionFactory.new(self)
     end
 
-    # Returns the current request token if it is set, else it creates
-    # and sets a new token.
-    def request_token
-      @request_token ||= get_request_token
-    end
-
-    # Sets the request token from a given token and secret.
-    def set_request_token(token, secret)
-      @request_token = OAuth::RequestToken.new(@consumer, token, secret)
-    end
-
-    # Initialises and returns a new access token from the params hash
-    # returned by the OAuth transaction.
-    def init_access_token(params)
-      @access_token = request_token.get_access_token(params)
-    end
-
-    # Sets the access token from a preexisting token and secret.
-    def set_access_token(token, secret)
-      @access_token = OAuth::AccessToken.new(@consumer, token, secret)
-    end
-
-    # Returns the current access token. Raises an
-    # JIRA::Client::UninitializedAccessTokenError exception if it is not set.
-    def access_token
-      raise UninitializedAccessTokenError.new unless @access_token
-      @access_token
-    end
-
     # HTTP methods without a body
     def delete(path, headers = {})
-      request(:delete, path,  merge_default_headers(headers))
+      request(:delete, path, nil, merge_default_headers(headers))
     end
+
     def get(path, headers = {})
-      request(:get, path, merge_default_headers(headers))
+      request(:get, path, nil, merge_default_headers(headers))
     end
+
     def head(path, headers = {})
-      request(:head, path, merge_default_headers(headers))
+      request(:head, path, nil, merge_default_headers(headers))
     end
 
     # HTTP methods with a body
@@ -157,21 +129,16 @@ module JIRA
       headers = {'Content-Type' => 'application/json'}.merge(headers)
       request(:post, path, body, merge_default_headers(headers))
     end
+
     def put(path, body = '', headers = {})
       headers = {'Content-Type' => 'application/json'}.merge(headers)
       request(:put, path, body, merge_default_headers(headers))
     end
 
     # Sends the specified HTTP request to the REST API through the
-    # OAuth token.
-    #
-    # Returns the response if the request was successful (HTTP::2xx) and
-    # raises a JIRA::HTTPError if it was not successful, with the response
-    # attached.
-    def request(http_method, path, *arguments)
-      response = access_token.request(http_method, path, *arguments)
-      raise HTTPError.new(response) unless response.kind_of?(Net::HTTPSuccess)
-      response
+    # appropriate method (oauth, basic).
+    def request(http_method, path, body = '', headers)
+      @request_client.request(http_method, path, body, headers)
     end
 
     protected

data/lib/jira/http_client.rb

@@ -0,0 +1,41 @@
+require 'json'
+require 'net/https'
+
+module JIRA
+  class HttpClient < RequestClient
+
+    DEFAULT_OPTIONS = {
+      :username           => '',
+      :password           => ''
+    }
+
+    attr_reader :options
+
+    def initialize(options)
+      @options = DEFAULT_OPTIONS.merge(options)
+    end
+
+    def make_request(http_method, path, body='', headers)
+      request = Net::HTTP.const_get(http_method.capitalize).new(path, headers)
+      request.body = body unless body.nil?
+      request.basic_auth(@options[:username], @options[:password])
+      response = basic_auth_http_conn.request(request)
+      response
+    end
+
+    def basic_auth_http_conn
+      http_conn(uri)
+    end
+
+    def http_conn(uri)
+      http_conn = Net::HTTP.new(uri.host, uri.port)
+      http_conn.use_ssl = @options[:use_ssl]
+      http_conn.verify_mode = @options[:ssl_verify_mode]
+      http_conn
+    end
+
+    def uri
+      uri = URI.parse(@options[:site])
+    end
+  end
+end

data/lib/jira/oauth_client.rb

@@ -0,0 +1,84 @@
+require 'oauth'
+require 'json'
+require 'forwardable'
+
+module JIRA
+  class OauthClient < RequestClient
+
+    DEFAULT_OPTIONS = {
+      :signature_method   => 'RSA-SHA1',
+      :request_token_path => "/plugins/servlet/oauth/request-token",
+      :authorize_path     => "/plugins/servlet/oauth/authorize",
+      :access_token_path  => "/plugins/servlet/oauth/access-token",
+      :private_key_file   => "rsakey.pem",
+      :consumer_key       => nil,
+      :consumer_secret    => nil
+    }
+
+    # This exception is thrown when the client is used before the OAuth access token
+    # has been initialized.
+    class UninitializedAccessTokenError < StandardError
+      def message
+        "init_access_token must be called before using the client"
+      end
+    end
+
+    extend Forwardable
+
+    attr_accessor :consumer
+    attr_reader :options
+
+    def_instance_delegators :@consumer, :key, :secret, :get_request_token
+
+    def initialize(options)
+      @options = DEFAULT_OPTIONS.merge(options)
+      @consumer = init_oauth_consumer(@options)
+    end
+
+    def init_oauth_consumer(options)
+      @options[:request_token_path] = @options[:context_path] + @options[:request_token_path]
+      @options[:authorize_path] = @options[:context_path] + @options[:authorize_path]
+      @options[:access_token_path] = @options[:context_path] + @options[:access_token_path]
+      OAuth::Consumer.new(@options[:consumer_key],@options[:consumer_secret],@options)
+    end
+
+    # Returns the current request token if it is set, else it creates
+    # and sets a new token.
+    def request_token
+      @request_token ||= get_request_token
+    end
+
+    # Sets the request token from a given token and secret.
+    def set_request_token(token, secret)
+      @request_token = OAuth::RequestToken.new(@consumer, token, secret)
+    end
+
+    # Initialises and returns a new access token from the params hash
+    # returned by the OAuth transaction.
+    def init_access_token(params)
+      @access_token = request_token.get_access_token(params)
+    end
+
+    # Sets the access token from a preexisting token and secret.
+    def set_access_token(token, secret)
+      @access_token = OAuth::AccessToken.new(@consumer, token, secret)
+    end
+
+    # Returns the current access token. Raises an
+    # JIRA::Client::UninitializedAccessTokenError exception if it is not set.
+    def access_token
+      raise UninitializedAccessTokenError.new unless @access_token
+      @access_token
+    end
+
+    def make_request(http_method, path, body='', headers)
+      case http_method
+      when :delete, :get, :head
+        response = access_token.send http_method, path, headers
+      when :post, :put
+        response = access_token.send http_method, path, body, headers
+      end
+      response
+    end
+  end
+end