jira-ruby 0.0.2

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc
+.rspec
+*.pem
+.DS_STORE
+doc

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in jira_api.gemspec
+gemspec
+gem 'rspec'

data/README.markdown

@@ -0,0 +1,81 @@
+Jira 5 API Gem
+==============
+
+Links to JIRA REST API documentation
+------------------------------------
+* [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs)
+* [Reference](http://docs.atlassian.com/jira/REST/5.0-rc1/)
+
+
+Setting up the JIRA SDK
+-----------------------
+On Mac OS,
+
+    brew install atlassian-plugin-sdk
+
+Otherwise:
+
+* Download the SDK from https://developer.atlassian.com/ (You will need
+  an Atlassian login for this)
+* Unpack the dowloaded archive
+* From within the archive directory, run:
+
+    ./bin/atlas-run-standalone --product jira --version 5.0-rc2
+
+Once this is running, you should be able to connect to
+[http://localhost:2990/] and login to the JIRA admin system using `admin:admin`
+
+You'll need to create a dummy project and probably some issues to test using
+this library.
+
+Configuring JIRA to use OAuth
+-----------------------------
+From the Jira API tutorial
+
+> The first step is to register a new consumer in JIRA. This is done through
+> the Application Links administration screens in JIRA. Create a new
+> Application Link.
+> [Administration/Plugins/Application Links](http://localhost:2990/jira/plugins/servlet/applinks/listApplicationLinks)
+> 
+> When creating the Application Link use a placeholder URL or the correct URL
+> to your client (e.g. `http://localhost:3000`), if your client can be reached
+> via HTTP and choose the Generic Application type. After this Application Link
+> has been created, edit the configuration and go to the incoming
+> authentication configuration screen and select OAuth. Enter in this the
+> public key and the consumer key which your client will use when making
+> requests to JIRA.
+
+This public key and consumer key will need to be generated by the Gem user, using OpenSSL 
+or similar to generate the public key and the provided rake task to generate the consumer 
+key.
+
+> After you have entered all the information click OK and ensure OAuth authentication is
+> enabled.
+
+Using the API Gem in your application
+-------------------------------------
+The JiraApi 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. These two pieces of information are applied globally to your application, with separate JiraApi::Client objects created on a per-user basis.
+
+An example initializer which sets the key and certificate filename in a pair of globals is shown below, myapp/config/initializers/jira\_api.rb:
+
+    $CONSUMER_KEY = 'cbaec507669c65979b6b6eefdb1c5bb0' #Your consumer key. Can be generated by rake jira_api:generate_public_cert 
+    $PUBLIC_CERT_FILE = 'rsakey.pem' #Location of the Private Key File (generated by rake jira_api:generate_public_cert 
+
+This allows acces to the variables when a session is being set up.
+The following sample controller shows how to set up and initialize an access token for a particular user session.
+(Note that the callback url is defined in the Jira application link interface, and can be placed wherever suits you best in your application. The session#callback method is simply an example)
+
+\#TODO cannot pass params hash straight into init\_access\_token method - errors with a missing parameter exception
+
+    class SessionsController < ApplicationController
+      def create
+        session[:client] = JiraApi::Client.new($CONSUMER_KEY, '', :private_key_file => $PUBLIC_CERT_FILE)
+        session[:request_token] = session[:client].request_token #Generate the request token
+        redirect_to session[:request_token].authorize_url   #Redirect to Jira to authorize the token
+      end
+    
+      def callback
+        session[:client].init_access_token(:oauth_verifier => params[:oauth_verifier]) #Initialize the access token
+        redirect_to root_url  #Redirect to the desired page after initializing the access token
+      end
+    end

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require 'rubygems'
+require 'rspec/core/rake_task'
+
+task :default => [:spec]
+
+desc "Run RSpec tests"
+RSpec::Core::RakeTask.new(:spec)

data/example.rb

@@ -0,0 +1,66 @@
+require 'pp'
+require './lib/jira'
+
+options = {
+  :private_key_file => "rsakey.pem"
+}
+
+CONSUMER_KEY = 'test'
+
+client = Jira::Client.new(CONSUMER_KEY, '', options)
+
+if ARGV.length == 0
+  # If not passed any command line arguments, open a browser and prompt the
+  # user for the OAuth verifier.
+  request_token = client.request_token
+  puts "Opening #{request_token.authorize_url}"
+  system "open #{request_token.authorize_url}"
+
+  puts "Enter the oauth_verifier: "
+  oauth_verifier = gets.strip
+
+  access_token = client.init_access_token(:oauth_verifier => oauth_verifier)
+  puts "Access token: #{access_token.token} secret: #{access_token.secret}"
+elsif ARGV.length == 2
+  # Otherwise assume the arguments are a previous access token and secret.
+  access_token = client.set_access_token(ARGV[0], ARGV[1])
+else
+  # Script must be passed 0 or 2 arguments
+  raise "Usage: #{$0} [ token secret ]"
+end
+
+# Show all projects
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
+end
+issue = client.Issue.find('SAMPLEPROJECT-1')
+pp issue
+
+# # Find a specific project by key
+# # ------------------------------
+# project = client.Project.find('SAMPLEPROJECT')
+# pp project
+#
+# # 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

data/jira-ruby.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "jira/version"
+
+Gem::Specification.new do |s|
+  s.name        = "jira-ruby"
+  s.version     = Jira::VERSION
+  s.authors     = ["Trineo Ltd"]
+  s.homepage    = "http://trineo.co.nz"
+  s.summary     = %q{Ruby Gem for use with the Atlassian Jira 5 REST API}
+  s.description = %q{API for Jira 5}
+
+  s.rubyforge_project = "jira-ruby"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "oauth"
+  s.add_development_dependency "oauth"
+  s.add_runtime_dependency "railties"
+  s.add_development_dependency "railties"
+  s.add_development_dependency "webmock"
+end

data/lib/jira.rb

@@ -0,0 +1,12 @@
+Dir[File.join(File.dirname(__FILE__),'tasks/*.rake')].each { |f| load f } if defined?(Rake)
+
+$: << File.expand_path(File.dirname(__FILE__))
+require 'jira/resource/base'
+require 'jira/resource/base_factory'
+require 'jira/resource/http_error'
+
+require 'jira/resource/issue'
+require 'jira/resource/project'
+require 'jira/resource/component'
+
+require 'jira/client'

data/lib/jira/client.rb

@@ -0,0 +1,105 @@
+require 'oauth'
+require 'json'
+require 'forwardable'
+
+module Jira
+  class Client
+
+    extend Forwardable
+
+    class UninitializedAccessTokenError < StandardError
+      def message
+        "init_access_token must be called before using the client"
+      end
+    end
+
+    attr_accessor :consumer
+    attr_reader :options
+    delegate [:key, :secret, :get_request_token] => :consumer
+
+    DEFAULT_OPTIONS = {
+      :site               => 'http://localhost:2990',
+      :signature_method   => 'RSA-SHA1',
+      :request_token_path => "/jira/plugins/servlet/oauth/request-token",
+      :authorize_path     => "/jira/plugins/servlet/oauth/authorize",
+      :access_token_path  => "/jira/plugins/servlet/oauth/access-token",
+      :private_key_file   => "rsakey.pem",
+      :rest_base_path     => "/jira/rest/api/2"
+    }
+
+    def initialize(consumer_key, consumer_secret, options={})
+      options = DEFAULT_OPTIONS.merge(options)
+
+      @options = options
+      @options.freeze
+      @consumer = OAuth::Consumer.new(consumer_key,consumer_secret,options)
+    end
+
+    def Project
+      Jira::Resource::ProjectFactory.new(self)
+    end
+
+    def Issue
+      Jira::Resource::IssueFactory.new(self)
+    end
+
+    def Component
+      Jira::Resource::ComponentFactory.new(self)
+    end
+
+    def request_token
+      @request_token ||= get_request_token
+    end
+
+    def set_request_token(token, secret)
+      @request_token = OAuth::RequestToken.new(@consumer, token, secret)
+    end
+
+    def init_access_token(params)
+      @access_token = request_token.get_access_token(params)
+    end
+
+    def set_access_token(token, secret)
+      @access_token = OAuth::AccessToken.new(@consumer, token, secret)
+    end
+
+    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))
+    end
+    def get(path, headers = {})
+      request(:get, path, merge_default_headers(headers))
+    end
+    def head(path, headers = {})
+      request(:head, path, merge_default_headers(headers))
+    end
+
+    # HTTP methods with a body
+    def post(path, body = '', headers = {})
+      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
+
+    def request(http_method, path, *arguments)
+      response = access_token.request(http_method, path, *arguments)
+      raise Resource::HTTPError.new(response) unless response.kind_of?(Net::HTTPSuccess)
+      response
+    end
+
+    protected
+
+      def merge_default_headers(headers)
+        {'Accept' => 'application/json'}.merge(headers)
+      end
+
+  end
+end

data/lib/jira/resource/base.rb

@@ -0,0 +1,148 @@
+module Jira
+  module Resource
+
+    class Base
+
+      attr_reader :client
+      attr_accessor :expanded, :deleted, :attrs
+      alias :expanded? :expanded
+      alias :deleted? :deleted
+
+      def initialize(client, options = {})
+        @client   = client
+        @attrs    = options[:attrs] || {}
+        @expanded = options[:expanded] || false
+        @deleted  = false
+      end
+
+      # The class methods are never called directly, they are always
+      # invoked from a BaseFactory subclass instance.
+      def self.all(client)
+        response = client.get(rest_base_path(client))
+        json = parse_json(response.body)
+        json.map do |attrs|
+          self.new(client, :attrs => attrs)
+        end
+      end
+
+      def self.find(client, key)
+        instance = self.new(client)
+        instance.attrs[key_attribute.to_s] = key
+        instance.fetch
+        instance
+      end
+
+      def self.build(client, attrs)
+        self.new(client, :attrs => attrs)
+      end
+
+      def self.rest_base_path(client)
+        client.options[:rest_base_path] + '/' + self.endpoint_name
+      end
+
+      def self.endpoint_name
+        self.name.split('::').last.downcase
+      end
+
+      def self.key_attribute
+        :key
+      end
+
+      def self.parse_json(string)
+        JSON.parse(string)
+      end
+
+      def respond_to?(method_name)
+        if attrs.keys.include? method_name.to_s
+          true
+        else
+          super(method_name)
+        end
+      end
+
+      def method_missing(method_name, *args, &block)
+        if attrs.keys.include? method_name.to_s
+          attrs[method_name.to_s]
+        else
+          super(method_name)
+        end
+      end
+
+      def rest_base_path
+        # Just proxy this to the class method
+        self.class.rest_base_path(client)
+      end
+
+      def fetch(reload = false)
+        return if expanded? && !reload
+        response = client.get(url)
+        set_attrs_from_response(response)
+        @expanded = true
+      end
+
+      def save(attrs)
+        http_method = new_record? ? :post : :put
+        response = client.send(http_method, url, attrs.to_json)
+        set_attrs(attrs, false)
+        set_attrs_from_response(response)
+        @expanded = false
+        true
+      end
+
+      def set_attrs_from_response(response)
+        unless response.body.nil? or response.body.length < 2
+          json = self.class.parse_json(response.body)
+          set_attrs(json)
+        end
+      end
+
+      # Set the current attributes from a hash.  If clobber is true, any existing
+      # hash values will be clobbered by the new hash, otherwise the hash will
+      # be deeply merged into attrs.  The target paramater is for internal use only
+      # and should not be used.
+      def set_attrs(hash, clobber=true, target = nil)
+        target ||= @attrs
+        if clobber
+          target.merge!(hash)
+          hash
+        else
+          hash.each do |k, v|
+            if v.is_a?(Hash)
+              set_attrs(v, clobber, target[k])
+            else
+              target[k] = v
+            end
+          end
+        end
+      end
+
+      def delete
+        client.delete(url)
+        @deleted = true
+      end
+
+      def url
+        if @attrs['self']
+          @attrs['self']
+        elsif @attrs[self.class.key_attribute.to_s]
+          rest_base_path + "/" + @attrs[self.class.key_attribute.to_s].to_s
+        else
+          rest_base_path
+        end
+      end
+
+      def to_s
+        "#<#{self.class.name}:#{object_id} @attrs=#{@attrs.inspect}>"
+      end
+
+      def to_json
+        attrs.to_json
+      end
+
+      def new_record?
+        @attrs['id'].nil?
+      end
+    end
+
+  end
+end