jira-ruby 0.0.2 → 0.0.3

data/lib/jira/base_factory.rb

@@ -0,0 +1,49 @@
+module JIRA
+
+  # This is the base class for all the JIRA resource factory instances.
+  class BaseFactory
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Return the name of the class which this factory generates, i.e. 
+    # JIRA::Resource::FooFactory creates JIRA::Resource::Foo instances.
+    def target_class
+      # Need to do a little bit of work here as Module.const_get doesn't work
+      # with nested class names, i.e. JIRA::Resource::Foo.
+      #
+      # So create a method chain from the class componenets.  This code will
+      # unroll to:
+      #   Module.const_get('JIRA').const_get('Resource').const_get('Foo')
+      #
+      target_class_name = self.class.name.sub(/Factory$/, '')
+      class_components = target_class_name.split('::')
+
+      class_components.inject(Module) do |mod, const_name|
+        mod.const_get(const_name)
+      end
+    end
+
+    def self.delegate_to_target_class(*method_names)
+      method_names.each do |method_name|
+        define_method method_name do |*args|
+          target_class.send(method_name, @client, *args)
+        end
+      end
+    end
+
+    # The priciple purpose of this class is to delegate methods to the corresponding
+    # non-factory class and automatically prepend the client argument to the argument
+    # list.
+    delegate_to_target_class :all, :find, :collection_path, :singular_path
+
+    # This method needs special handling as it has a default argument value
+    def build(attrs={})
+      target_class.build(@client, attrs)
+    end
+
+  end
+end

data/lib/jira/client.rb

@@ -2,19 +2,44 @@ require 'oauth'
 require 'json'
 require 'forwardable'
 
-module Jira
+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:
+  #
+  #   :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"
+  #
+  #
+  # 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 configuration options for this client instance
     attr_reader :options
+
     delegate [:key, :secret, :get_request_token] => :consumer
 
     DEFAULT_OPTIONS = {
@@ -35,34 +60,74 @@ module Jira
       @consumer = OAuth::Consumer.new(consumer_key,consumer_secret,options)
     end
 
-    def Project
-      Jira::Resource::ProjectFactory.new(self)
+    def Project # :nodoc:
+      JIRA::Resource::ProjectFactory.new(self)
+    end
+
+    def Issue # :nodoc:
+      JIRA::Resource::IssueFactory.new(self)
+    end
+
+    def Component # :nodoc:
+      JIRA::Resource::ComponentFactory.new(self)
+    end
+
+    def User # :nodoc:
+      JIRA::Resource::UserFactory.new(self)
+    end
+
+    def Issuetype # :nodoc:
+      JIRA::Resource::IssuetypeFactory.new(self)
+    end
+
+    def Priority # :nodoc:
+      JIRA::Resource::PriorityFactory.new(self)
+    end
+
+    def Status # :nodoc:
+      JIRA::Resource::StatusFactory.new(self)
+    end
+
+    def Comment # :nodoc:
+      JIRA::Resource::CommentFactory.new(self)
+    end
+
+    def Attachment # :nodoc:
+      JIRA::Resource::AttachmentFactory.new(self)
     end
 
-    def Issue
-      Jira::Resource::IssueFactory.new(self)
+    def Worklog # :nodoc:
+      JIRA::Resource::WorklogFactory.new(self)
     end
 
-    def Component
-      Jira::Resource::ComponentFactory.new(self)
+    def Version # :nodoc:
+      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
@@ -89,9 +154,15 @@ module Jira
       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 Resource::HTTPError.new(response) unless response.kind_of?(Net::HTTPSuccess)
+      raise HTTPError.new(response) unless response.kind_of?(Net::HTTPSuccess)
       response
     end
 

data/lib/jira/has_many_proxy.rb

@@ -0,0 +1,43 @@
+#
+# Whenever a collection from a has_many relationship is accessed, an instance
+# of this class is returned.  This instance wraps the Array of instances in
+# the collection with an extra build method, which allows new instances to be
+# built on the collection with the correct properties.
+#
+# In practice, instances of this class behave exactly like an Array.
+#
+class JIRA::HasManyProxy
+
+  attr_reader :target_class, :parent
+  attr_accessor :collection
+
+  def initialize(parent, target_class, collection = [])
+    @parent       = parent
+    @target_class = target_class
+    @collection   = collection
+  end
+
+  # Builds an instance of this class with the correct parent.
+  # For example, issue.comments.build(attrs) will initialize a
+  # comment as follows:
+  #
+  #   JIRA::Resource::Comment.new(issue.client,
+  #                               :attrs => attrs,
+  #                               :issue => issue)
+  def build(attrs = {})
+    resource = target_class.new(parent.client, :attrs => attrs, parent.to_sym => parent)
+    collection << resource
+    resource
+  end
+
+  # Forces an HTTP request to fetch all instances of the target class that
+  # are associated with the parent
+  def all
+    target_class.all(parent.client, parent.to_sym => parent)
+  end
+
+  # Delegate any missing methods to the collection that this proxy wraps
+  def method_missing(method_name, *args, &block)
+    collection.send(method_name, *args, &block)
+  end
+end

data/lib/jira/http_error.rb

@@ -0,0 +1,16 @@
+require 'forwardable'
+module JIRA
+
+  class HTTPError < StandardError
+    extend Forwardable
+
+    delegate [:message, :code] => :response
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+
+  end
+
+end

data/lib/jira/resource/attachment.rb

@@ -0,0 +1,12 @@
+module JIRA
+  module Resource
+
+    class AttachmentFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Attachment < JIRA::Base
+      has_one :author, :class => JIRA::Resource::User
+    end
+
+  end
+end

data/lib/jira/resource/comment.rb

@@ -0,0 +1,14 @@
+module JIRA
+  module Resource
+
+    class CommentFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Comment < JIRA::Base
+      belongs_to :issue
+
+      nested_collections true
+    end
+
+  end
+end

data/lib/jira/resource/component.rb

@@ -1,15 +1,10 @@
-module Jira
+module JIRA
   module Resource
 
-    class ComponentFactory < BaseFactory ; end
-
-    class Component < Base
-    
-      def self.key_attribute
-        :id
-      end
-
+    class ComponentFactory < JIRA::BaseFactory # :nodoc:
     end
 
+    class Component < JIRA::Base ; end
+
   end
 end

data/lib/jira/resource/issue.rb

@@ -1,12 +1,56 @@
-module Jira
+module JIRA
   module Resource
 
-    class IssueFactory < BaseFactory ; end
+    class IssueFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Issue < JIRA::Base
+
+      has_one :reporter,  :class => JIRA::Resource::User,
+                          :nested_under => 'fields'
+      has_one :assignee,  :class => JIRA::Resource::User,
+                          :nested_under => 'fields'
+      has_one :project,   :nested_under => 'fields'
+
+      has_one :issuetype, :nested_under => 'fields'
+
+      has_one :priority,  :nested_under => 'fields'
+
+      has_one :status,    :nested_under => 'fields'
+
+      has_many :components, :nested_under => 'fields'
 
-    class Issue < Base
+      has_many :comments, :nested_under => ['fields','comment']
+
+      has_many :attachments, :nested_under => 'fields',
+                          :attribute_key => 'attachment'
+
+      has_many :versions, :nested_under => 'fields'
+
+      has_many :worklogs, :nested_under => ['fields','worklog']
+
+      def self.all(client)
+        response = client.get(client.options[:rest_base_path] + "/search")
+        json = parse_json(response.body)
+        json['issues'].map do |issue|
+          client.Issue.build(issue)
+        end
+      end
+
+      def respond_to?(method_name)
+        if attrs.keys.include?('fields') && attrs['fields'].keys.include?(method_name.to_s)
+          true
+        else
+          super(method_name)
+        end
+      end
 
-      def self.key_attribute
-        :id
+      def method_missing(method_name, *args, &block)
+        if attrs.keys.include?('fields') && attrs['fields'].keys.include?(method_name.to_s)
+          attrs['fields'][method_name.to_s]
+        else
+          super(method_name)
+        end
       end
 
     end

data/lib/jira/resource/issuetype.rb

@@ -0,0 +1,10 @@
+module JIRA
+  module Resource
+
+    class IssuetypeFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Issuetype < JIRA::Base ; end
+
+  end
+end

data/lib/jira/resource/priority.rb

@@ -0,0 +1,10 @@
+module JIRA
+  module Resource
+
+    class PriorityFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Priority < JIRA::Base ; end
+
+  end
+end

data/lib/jira/resource/project.rb

@@ -1,9 +1,30 @@
-module Jira
+module JIRA
   module Resource
 
-    class ProjectFactory < BaseFactory ; end
+    class ProjectFactory < JIRA::BaseFactory # :nodoc:
+    end
 
-    class Project < Base ; end
+    class Project < JIRA::Base
+
+      has_one :lead, :class => JIRA::Resource::User
+      has_many :components
+      has_many :issuetypes, :attribute_key => 'issueTypes'
+      has_many :versions
+
+      def self.key_attribute
+        :key
+      end
+
+      # Returns all the issues for this project
+      def issues
+        response = client.get(client.options[:rest_base_path] + "/search?jql=project%3D'#{key}'")
+        json = self.class.parse_json(response.body)
+        json['issues'].map do |issue|
+          client.Issue.build(issue)
+        end
+      end
+
+    end
 
   end
 end

data/lib/jira/resource/status.rb

@@ -0,0 +1,10 @@
+module JIRA
+  module Resource
+
+    class StatusFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class Status < JIRA::Base ; end
+
+  end
+end

data/lib/jira/resource/user.rb

@@ -0,0 +1,14 @@
+module JIRA
+  module Resource
+
+    class UserFactory < JIRA::BaseFactory # :nodoc:
+    end
+
+    class User < JIRA::Base
+      def self.singular_path(client, key, prefix = '/')
+        collection_path(client, prefix) + '?username=' + key
+      end
+    end
+
+  end
+end