mingle4r 0.3.0 → 0.4.0

data/History.txt

@@ -1,3 +1,9 @@
+0.4.0
+-----
+
+* Only Mingle 3.0 is supported. If you need to work with both mingle 3.0 and mingle 2.0 use the 0.3.0 of the gem.
+However no new features will be supported by 0.3.0.
+
 0.3.0
 -----
 

data/README

@@ -8,6 +8,8 @@ This gem is a wrapper around active resource to access the rest api exposed by m
 (http://studios.thoughtworks.com/mingle-agile-project-management).It provides a easy 
 way to communicate with mingle. For the library to work you need to enable basic authentication
 (not enabled by default) in Mingle. See below to enable basic authentication in Mingle.
+The typical use-case for this gem is to help someone getting started with writing code
+to integrate with Mingle.
 
 However if you are planning to connect and work with mingle from the terminal, then there
 is another gem mingle-mingle which you should look at. This library provides a very easy
@@ -29,10 +31,9 @@ attachments for a particular card.
 
 == SYNOPSIS:
 
-The api now supports both mingle 2 and mingle 3. The gem tries as much as possible to hide
-away the internal details. But some api features are only supported in mingle 3 only (like
-murmurs). For that check the api documentation for the mingle instance(located at 
-<mingle instance host>/help/index)
+The api now supports only mingle 3. Mingle 2 is no longer supported. If you need to connect
+to both Mingle 2 and Mingle 3 then try 0.3.0 of the gem. To see the api for mingle 3, check
+the api documentation for the mingle instance(located at <mingle instance host>/help/index)
 
 In all the documentation below you can replace Mingle4r::MingleClient with MingleClient.
 Its an alias for easy use.
@@ -70,10 +71,12 @@ you are trying to access. It should be something like 'http://localhost:8080/pro
 
 		m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
 		m_c.proj_id = 'great_mingle_project'
-		m_c.project
+		project = m_c.project
+		
+		project is a single activeresource object
 
 C) Getting cards for a particular project
---------------------------------------
+-----------------------------------------
 
 Get a mingle client object initialized as in SECTION B. Then call the cards method.
 
@@ -113,6 +116,7 @@ m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password'
 m_c.proj_id = 'great_mingle_project'
 defect_card = m_c.project.cards.first
 defect_card.property_value('Status', 'Closed')
+defect_card.save
 
 G) Adding comment to a particular card
 --------------------------------------
@@ -122,14 +126,42 @@ m_c.proj_id = 'great_mingle_project'
 defect_card = m_c.project.cards[0]
 defect_card.add_comment('Not able to reproduce')
 
-H) Getting all comments for a card(only in mingle 3.0)
-------------------------------------------------------
+H) Getting a particular version of a card
+-----------------------------------------
+
+Mingle maintains the different versions of a card. It always shows the latest version
+by default. However if you want to access a different version you can do so in the
+following ways.
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+supposing the latest version of the card is 42
+
+  1) Get the previous version
+  ---------------------------
+  
+  defect_card.version(:previous) # return version 41
+  
+  2) Get the next version
+  -----------------------
+  
+  defect_card.version(:next) # returns version 42 since it is the latest version
+  
+  3) Get an arbitrary version
+  ---------------------------
+  
+  defect_card.version(21) # returns version 21
+
+I) Getting all comments for a card
+----------------------------------
+
 m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
 m_c.proj_id = 'great_mingle_project'
 defect_card = m_c.project.cards.first
 defect_cards.comments
 
-I) Attachments
+J) Attachments
 --------------
 m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
 m_c.proj_id = 'great_mingle_project'
@@ -140,15 +172,15 @@ defect_card.attachments
   --------------------------------------
   
   attachment = defect_card.attachments.first
-  attachment.save('page.css')
+  attachment.download('page.css')
   
   2) Uploading an attachment
   --------------------------
   
   defect_card.upload_attachment('page-screenshot.jpg')
   
-J) Murmurs(only in Mingle 3.0)
-------------------------------
+K) Murmurs
+----------
 
   1) Get the murmurs for a project
   --------------------------------
@@ -168,16 +200,16 @@ J) Murmurs(only in Mingle 3.0)
   -------------------------
   project.post_murmur('my first murmur, I am excited!')
   
-K) Get all transitions for a card(only in Mingle 3.0)
------------------------------------------------------
+L) Get all transitions for a card
+---------------------------------
 
 m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
 m_c.proj_id = 'great_mingle_project'
 defect_card = m_c.project.cards.first
 
-defect_card.transitions
+defect_card.transitions # array of active resource objects
 
-L) Execute a transition on a card
+M) Execute a transition on a card
 ---------------------------------
 
 m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
@@ -185,11 +217,9 @@ m_c.proj_id = 'great_mingle_project'
 defect_card = m_c.project.cards.first
 
 defect_card.execute_transition(
- 'name'/'transition' => name of the transition to execute exactly s in Mingle(required in 2,3 but
-not required in 3.0)
  'comment' => comment for the transition, required only if the transition requires a comment
  'Property Name as in Mingle exactly' => 'Property value to set for the property', required only
-if the transition requires to be set manually.
+if the transition requires to be set manually, multiple properties might need to be set.
 )
 
 == REQUIREMENTS:
@@ -199,7 +229,10 @@ during gem install.
 
 == INSTALL:
 
-sudo (not on windows) gem install mingle4r
+since github no longer archives gems, I am hosting the gem at gemcutter. So you would need to
+add http://gemcutter.org to your gem sources : gem sources -a 'http://gemcutter.org'. Then do
+
+gem install mingle4r
 
 == LICENSE:
 

data/TODO.txt

@@ -1,7 +1,11 @@
-update documentation
-write tests for mingle4r/mingle_client
+update documentation - write about executing transitions directly on the transition
+write tests for project class
+
 
 refactorings
 ------------
-remove calling create_resource_class through send
-remove checking for cache through a variable. check the results container directly
+
+maybe nice to  nave
+-------------------
+
+should transtions give the list of properties to be changed directly

data/lib/mingle4r.rb

@@ -13,29 +13,15 @@ end
 require 'mingle_resource'
 require 'mingle4r/version'
 require 'mingle4r/common_class_methods'
-require 'mingle4r/common_dyn_class_instance_methods'
 require 'mingle4r/helpers'
 require 'mingle4r/mingle_client'
-require 'mingle4r/api'
 
-# Version 1 of api
-require 'mingle4r/api/v1'
-require 'mingle4r/api/v1/card'
-require 'mingle4r/api/v1/card/attachment'
-require 'mingle4r/api/v1/project'
-require 'mingle4r/api/v1/property_definition'
-require 'mingle4r/api/v1/transition_execution'
-require 'mingle4r/api/v1/user'
-require 'mingle4r/api/v1/wiki'
-
-# version 2 of api
-require 'mingle4r/api/v2'
-require 'mingle4r/api/v2/card'
-require 'mingle4r/api/v2/card/attachment'
-require 'mingle4r/api/v2/card/comment'
-require 'mingle4r/api/v2/card/transition'
-require 'mingle4r/api/v2/murmur'
-require 'mingle4r/api/v2/project'
-require 'mingle4r/api/v2/property_definition'
-require 'mingle4r/api/v2/user'
-require 'mingle4r/api/v2/wiki'
+require 'mingle4r/api/card'
+require 'mingle4r/api/card/attachment'
+require 'mingle4r/api/card/comment'
+require 'mingle4r/api/card/transition'
+require 'mingle4r/api/murmur'
+require 'mingle4r/api/project'
+require 'mingle4r/api/property_definition'
+require 'mingle4r/api/user'
+require 'mingle4r/api/wiki'

data/lib/mingle4r/api/card.rb

@@ -0,0 +1,137 @@
+module Mingle4r
+  module API
+    class Card  
+      extend Mingle4r::CommonClassMethods
+      
+      # overwrite the default find in CommonClassMethods
+      def self.find(*args)
+        scope = args.slice!(0)
+        options = args.slice!(0) || {}
+        @resource_class.find_without_pagination(scope, options)
+      end
+      
+      module ClassMethods
+        def find_without_pagination(*args)
+          scope   = args.slice!(0)
+          options = args.slice!(0) || {}
+          options[:params] ||= {}
+          options[:params].merge!({:page => 'all'})
+          # call ActiveResource::Base::find with proper options
+          find(scope, options)
+        end
+
+        # applies an mql filter on card types. Look at https://mingle05.thoughtworks.com/help/mql_reference.html
+        # for reference
+        def apply_filter(filter_string)
+          find_without_pagination(:all, :params => {'filters[mql]'.to_sym => filter_string})
+        end
+      end
+
+      module InstanceMethods
+        # so that active resource tries to find by number
+        def id
+          number()
+        end
+
+        def attachments(refresh = false)
+          return @attachments if(!refresh && @attachments)
+          set_attributes_for(Attachment)
+          @attachments = Attachment.find(:all)
+        end
+        
+        def comments(refresh = false)
+          return @comments if(!refresh && @comments)
+          set_attributes_for(Comment)
+          @comments = Card::Comment.find(:all)
+        end
+        
+        def transitions(refresh = false)
+          return @transitions if(!refresh && @transitions)
+          set_attributes_for(Transition)
+          @transitions = Card::Transition.find(:all)
+        end
+        
+        def murmurs(refresh = false)
+          return @murmurs if(!refresh && @murmurs)
+          set_attributes_for(Murmur)
+          @murmurs = Murmur.find(:all)
+        end
+        
+        def upload_attachment(file_path)
+          attachment_uri   = URI.parse(File.join(self.class.site.to_s, "cards/#{self.number()}/attachments.xml"))
+          http             = Net::HTTP.new(attachment_uri.host, attachment_uri.port)
+          http.use_ssl     = attachment_uri.is_a?(URI::HTTPS)
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE if http.use_ssl
+          basic_encode     = 'Basic ' + ["#{self.class.user}:#{self.class.password}"].pack('m').delete("\r\n")
+
+          post_headers = {
+            'Authorization' => basic_encode,
+            'Content-Type'  => 'multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1'
+          }
+
+          file_content = IO.read(file_path)
+
+          post_body = <<EOS
+------------XnJLe9ZIbbGUYtzPQJ16u1\r
+Content-Disposition: form-data; name="file"; filename="#{File.basename(file_path)}"\r
+Content-Type: application/octet-stream\r
+Content-Length: #{file_content.size}\r
+\r
+#{file_content}\r
+------------XnJLe9ZIbbGUYtzPQJ16u1--\r
+EOS
+      
+          http.post(attachment_uri.path, post_body, post_headers)
+        end
+        
+        def add_comment(str)
+          set_attributes_for(Comment)
+          comment = Comment.new(:content => str.to_s)
+          comment.save
+        end
+        
+        def execute_transition(args)
+          trans_name = args.symbolize_keys[:name]
+          transition = transitions.detect { |t| t.name ==  trans_name}
+          transition.execute(args)
+        end
+        
+        # returns back the version of the card given. If an invalid version is given, the latest
+        # version is returned, takes a number or :next or :before
+        def version(version_no)
+          version_2_find = 0
+          case version_no
+          when :previous
+            version_2_find = self.version.to_i - 1
+          when :next
+            version_2_find = self.version.to_i + 1
+          else
+            version_2_find = version_no.to_i
+          end
+          self.class.find(self.number, :params => {:version => version_2_find})
+        end
+        
+        # Gets and sets the value of a property. The property name given should be the same
+        # as the mingle property name. the value is optional
+        def property_value(name, val = nil)
+          property = properties.detect { |p| p.name == name }
+          val ? property.value = val : property.value
+        end
+    
+        # Gets the custom properties in the form of an array of hashes with the property names as keys and
+        # property values as the value
+        def custom_properties
+          properties.map { |p| {p.name => p.value} }
+        end
+        
+        private
+        def set_attributes_for(klass)
+          resource_site  = File.join(self.class.site.to_s, "cards/#{self.number()}").to_s
+          klass.site     = resource_site
+          klass.user     = self.class.user
+          klass.password = self.class.password
+        end
+      end
+    end
+  end
+end

data/lib/mingle4r/api/card/attachment.rb

@@ -0,0 +1,47 @@
+module Mingle4r
+  module API
+    class Attachment
+      module InstanceMethods
+        # downloads the attachment. It an additional file path is given it saves it at the 
+        # given path. The given path should be writable
+        def download(file_name = nil)
+          collection_uri = self.class.site
+          rel_down_url = self.url
+          base_url = "#{collection_uri.scheme}://#{collection_uri.host}:#{collection_uri.port}/"
+          down_uri = URI.join(base_url, rel_down_url)
+          req = Net::HTTP::Get.new(down_uri.path)
+          req.basic_auth self.class.user, self.class.password
+          begin
+            res = Net::HTTP.start(down_uri.host, down_uri.port) { |http| http.request(req) }
+            file_name ||= self.file_name()
+            File.open(file_name, 'w') { |f| f.print(res.body) }
+          rescue Exception => e
+            e.message
+          end
+        end # download
+
+        # alias for file_name
+        def name
+          file_name()
+        end
+
+        # so that active resource tries to find by proper id
+        def id
+          name()
+        end
+
+        # This method had to be overriden. 
+        # normal active resource destroy doesn't work as mingle site for deleting attachments doesn't end with .xml.
+        def destroy
+          connection = self.send(:connection)
+          # deletes the attachment by removing .xml at the end
+          connection.delete(self.send(:element_path).gsub(/\.xml\z/, ''))
+        end
+        alias_method :delete, :destroy
+      end #module InstanceMethods
+
+      extend Mingle4r::CommonClassMethods
+
+    end # class Attachment
+  end # class API
+end # module Mingle4r

data/lib/mingle4r/api/card/comment.rb

@@ -0,0 +1,12 @@
+module Mingle4r
+  module API
+    class Comment
+      module InstanceMethods
+        def to_s
+          attributes['content']
+        end
+      end
+      extend Mingle4r::CommonClassMethods
+    end
+  end
+end

data/lib/mingle4r/api/card/transition.rb

@@ -0,0 +1,48 @@
+module Mingle4r
+  module API
+    class Transition
+      extend Mingle4r::CommonClassMethods
+
+      module InstanceMethods
+        def execute(args = {})
+          args.symbolize_keys!
+          trans_exec_xml = convert_to_xml(args)
+          # set_transition_execution_attributes
+          conn = self.class.connection
+          url_path =URI.parse(transition_execution_url()).path 
+          conn.post(url_path, trans_exec_xml, self.class.headers)
+        end
+
+        private
+        def convert_to_xml(args)
+          hash = create_transition_exec_hash(args)
+          xmlize_trans_exec(hash)
+        end
+
+        def create_transition_exec_hash(args)
+          transition_hash = {}
+          transition_hash['card'] = (args.delete(:card) || associated_card_number).to_i
+          args.delete(:name) || args.delete(:transition)
+
+          comment = args.delete(:comment)
+          transition_hash['comment'] = comment if comment
+          properties = []
+          args.each do |name, value|
+            property = {'name' => name.to_s, 'value' => value}
+            properties.push(property)
+          end
+          transition_hash['properties'] = properties unless properties.empty?
+          transition_hash
+        end
+
+        def xmlize_trans_exec(hash)
+          hash.to_xml(:root => 'transition_execution', :dasherize => false)
+        end
+
+        def associated_card_number
+          File.basename(self.class.site.to_s).to_i
+        end
+      end
+    end
+  end
+end