jiraSOAP 0.7.1 → 0.8.0

data/.yardopts

@@ -1,10 +1,9 @@
 --protected
---private
 --no-cache
 --markup markdown
 --readme README.markdown
---load './yard-jiraSOAP.rb'
 lib/**/*.rb
 -
-LICENSE.txt
+docs/GettingStarted.markdown
 ChangeLog
+LICENSE.txt

data/ChangeLog

@@ -1,4 +1,19 @@
+Version 0.8.0
+
+	* Deprecated the #get_ from methods that start with #get_
+	* Alias #login to #log_in and #logout to #log_out
+	* Added RemoteAPI#permission_to_edit_comment?
+	* Added UserGroup and related RemoteAPI methods
+	* Added RemoteAPI#add_worklog
+	* Various documentation updates and tweaks
+
+	* Removed handsoap parsing abstraction (roflscale for parsing)
+	* Removed the YARD plugin in favour of YARD 0.7 DSL documenting stuff
+
+	* FIx setting the assignee during Issue creation
+
 Version 0.7.1
+
 	* Remove AOT compiled files from gem
 
 Version 0.7

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Mark Rada
+Copyright (c) 2010-2011 Marketcircle Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -1,74 +1,85 @@
-jiraSOAP - Ruby interface to the JIRA SOAP API
-==============================================
+# jiraSOAP - Ruby interface to the JIRA SOAP API
 
-Uses [handsoap](http://wiki.github.com/unwire/handsoap/) to build a client for the JIRA SOAP API that works on MacRuby as well as Ruby 1.9.
+Uses [handsoap](http://wiki.github.com/unwire/handsoap/) to build a
+client for the JIRA SOAP API that works on MacRuby as well as Ruby
+1.9.
 
-Read the documentation [here](http://rdoc.info/github/Marketcircle/jiraSOAP/master/frames). The meat of the service is in the `RemoteAPI` module.
+You can read the documentation for the
+[latest release](http://rubydoc.info/gems/jiraSOAP/) or
+the
+[HEAD commit](http://rdoc.info/github/Marketcircle/jiraSOAP/master/frames).
+The meat of the service is in the `RemoteAPI` module.
 
 
-Motivation
-----------
+## Motivation
 
-The `jira4r` gem already exists, and works well on Ruby 1.8, but is not compatible with Ruby 1.9 or MacRuby due to its dependance on `soap4r`.
+The `jira4r` gem already exists, and works well on Ruby 1.8, but is
+not compatible with Ruby 1.9 or MacRuby due to its dependance on
+`soap4r`.
 
 
-Goals
------
+## Goals
 
 Pick up where `jira4r` left off:
 
 - Implement the current API; `jira4r` does not implement APIs from JIRA 4.x
+   * not including APIs that have been deprecated in JIRA 4.x
 - More natural interface; not adhering to the API when the API is weird
-- Speed; network latency is bad enough
-- Excellent documentation, since the documentation given by Atlassian can be terse (the newer APIs are documented)
+- Speed; network latency is bad enough (it would be cool to roflscale)
+- Excellent documentation
 
 
-Getting Started
----------------
+## Getting Started
 
 `jiraSOAP` should run on Ruby 1.9.2 and MacRuby 0.8 or newer. It is available through rubygems or you can build from source:
 
-        # Using rubygems
-        sudo gem install jiraSOAP
+```bash
+# Using rubygems
+gem install jiraSOAP
 
-        # Building from source
-        git clone git://github.com/Marketcircle/jiraSOAP.git
-        rake build install
+# Building from source
+git clone git://github.com/Marketcircle/jiraSOAP.git
+rake build install
+```
 
 Once installed, you can run a quick demo (making appropriate substitutions):
 
-     require 'jiraSOAP'
+```ruby
+require 'jiraSOAP'
 
-     db = JIRA::JIRAService.new 'http://jira.yourSite.com:8080'
-     db.login 'user', 'password'
+db = JIRA::JIRAService.new 'http://jira.yourSite.com:8080'
+db.login 'user', 'password'
 
-     issues = db.get_issues_from_jql_search 'reporter = currentUser()', 100
-     issues.each { |issue|
-       #do something...
-       puts issue.key
-     }
+issues = db.get_issues_from_jql_search 'reporter = currentUser()', 100
+issues.each { |issue|
+  #do something...
+  puts issue.key
+}
 
-     db.logout
+db.logout
+```
 
 
-TODO
-----
+## TODO
 
 - Finish implementing all of the API
 - Stabilize API
 - Performance optimizations; there are a number of places that can be optimized
-  + Using GCD/Threads for parsing arrays of results; a significant speed up for large types and large arrays (ie. creating issues from JQL searches)
+  + Using GCD/Threads for parsing arrays of results; a significant
+  speed up for large types and large arrays (ie. creating issues from
+  JQL searches)
+  + Parsing can be done with array indexing instead of hash lookups
+  + Use a different web driver backend (net/http is slow under load)
 - Public test suite
   + Needs a lot of mock data
+- ActiveRecord inspired conveniences
+  + ProjectRole.new( 'test role' ).unique? # => check uniqueness
+  + Issue.new( args ).create! # => creates a new issue
+  + Issue.with_key( 'JIRA-123' ) # => returns result of issue lookup
+  + Issue.new( args ).project # => returns a JIRA::Project
 
 
-Note on Patches/Pull Requests
------------------------------
-
-This project has a tendancy to change drastically between releases as it
-is still unstable, so patches may not cleanly apply.
-
-If you want to help by submitting patches:
+## Note on Patches/Pull Requests
 
 * Fork the project.
 * Make your feature addition or bug fix.
@@ -80,9 +91,8 @@ If you want to help by submitting patches:
 * Send me a pull request. Bonus points for topic branches.
 
 
-License
--------
+## License
 
-Copyright: [Marketcircle Inc.](http://www.marketcircle.com/), 2010
+Copyright: [Marketcircle Inc.](http://www.marketcircle.com/), 2010-2011
 
-See LICENSE for details.
+See LICENSE.txt for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+
+task :default => :test
+
+
+### MACRUBY BONUSES
+
+if RUBY_ENGINE == 'macruby' and MACRUBY_REVISION.match(/^git commit/)
+  require 'rake/compiletask'
+  Rake::CompileTask.new do |t|
+    t.files = FileList["lib/**/*.rb"]
+    t.verbose = true
+  end
+
+  desc 'Clean MacRuby binaries'
+  task :clean do
+    FileList["lib/**/*.rbo"].each { |bin| rm bin }
+  end
+end
+
+
+### GEM STUFF
+
+require 'rake/gempackagetask'
+spec = Gem::Specification.load('jiraSOAP.gemspec')
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = true
+end
+
+require 'rubygems/dependency_installer'
+desc 'Build the gem and install it'
+task :install => :gem do
+  Gem::DependencyInstaller.new.install "pkg/#{spec.file_name}"
+end
+
+
+### TESTING
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs     << 'test'
+  t.pattern   = 'test/**/test_*.rb'
+  t.ruby_opts = ['-rhelper']
+  t.verbose   = true
+end
+
+desc 'Startup irb with jiraSOAP loaded'
+task :console do
+  sh 'irb -Ilib -rubygems -rjiraSOAP'
+end
+
+
+### DOCUMENTATION
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/docs/GettingStarted.markdown

@@ -0,0 +1,36 @@
+ Getting Started
+===============
+
+`jiraSOAP` should run on Ruby 1.9.2+ and MacRuby 0.8+. It is available through rubygems or you can build from source:
+
+    # Using rubygems
+    gem install jiraSOAP
+
+    # Building from source
+    git clone git://github.com/Marketcircle/jiraSOAP.git
+    rake build install
+
+Once installed, you can run a quick demo (making appropriate substitutions):
+
+    require 'jiraSOAP'
+
+The first thing that you need to do is create a JIRAService object:
+
+    db = JIRA::JIRAService.new 'http://jira.yourSite.com:8080'
+
+Then you need to log in (a failed login will raise an exception):
+
+    db.login 'mrada', 'secret'
+
+Once you are logged in, you can start querying the server for information:
+
+     issues = db.get_issues_from_jql_search 'reporter = currentUser()', 100
+     issues.each { |issue|
+       #do something...
+       puts issue.key
+     }
+
+Don't forget to log out when you are done:
+
+    db.logout
+

data/lib/jiraSOAP.rb

@@ -1,19 +1,22 @@
 require 'time'
 require 'uri'
+
 require 'nokogiri'
+require 'jiraSOAP/nokogiri_extensions'
 
 require 'handsoap'
 Handsoap.http_driver = :net_http
+require 'jiraSOAP/handsoap_extensions'
 
 require 'jiraSOAP/url'
-require 'jiraSOAP/handsoap_extensions'
+require 'jiraSOAP/macruby_extensions' if RUBY_ENGINE == 'macruby'
 
+##
 # All the remote entities as well as the SOAP service client.
 module JIRA
 end
 
+require 'jiraSOAP/version'
 require 'jiraSOAP/entities'
 require 'jiraSOAP/api'
-require 'jiraSOAP/JIRAservice'
-
-require 'jiraSOAP/macruby_bonuses' if RUBY_ENGINE == 'macruby'
+require 'jiraSOAP/jira_service'

data/lib/jiraSOAP/api.rb

@@ -1,78 +1,77 @@
-require 'jiraSOAP/api/users'
+require 'jiraSOAP/api/additions'
+require 'jiraSOAP/api/attachments'
 require 'jiraSOAP/api/avatars'
-require 'jiraSOAP/api/versions'
-require 'jiraSOAP/api/projects'
+require 'jiraSOAP/api/comments'
+require 'jiraSOAP/api/filters'
+require 'jiraSOAP/api/issue_data_types'
+require 'jiraSOAP/api/issues'
 require 'jiraSOAP/api/project_roles'
+require 'jiraSOAP/api/projects'
 require 'jiraSOAP/api/schemes'
-require 'jiraSOAP/api/issues'
-require 'jiraSOAP/api/filters'
 require 'jiraSOAP/api/server_info'
-require 'jiraSOAP/api/attachments'
-require 'jiraSOAP/api/comments'
-require 'jiraSOAP/api/issue_data_types'
-require 'jiraSOAP/api/additions'
-
-module JIRA
+require 'jiraSOAP/api/users'
+require 'jiraSOAP/api/versions'
+require 'jiraSOAP/api/worklog'
 
+##
+# @todo progressWorkflowAction and friends
+# @todo monkey patch Array to include a #to_soap method
+#
 # Contains the API defined by Atlassian for the [JIRA SOAP service](http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html).
 #
 # There are several cases where this API diverges from the one defined by
 # Atlassian; most notably, this API tries to be more idomatically Ruby by using
 # snake case for method names, default values, varargs, etc..
-# @todo logging
-# @todo progressWorkflowAction and friends [target v0.8]
-# @todo get Nokogiri element directly and monkey patch nokogiri directly
-#  instead of the handsoap wrapper
-# @todo remove the get_ prefix from api methods that don't need them
-# @todo monkey patch Array to include a #to_soap method
-# @todo document how to override the url_class setting
-module RemoteAPI
-
-  # XPath constant to get a node containing a response array.
-  # This could be used for all responses, but is only used in cases where we
-  # cannot use a more blunt XPath expression.
-  RESPONSE_XPATH = '/node()[1]/node()[1]/node()[1]/node()[2]'
-
+module JIRA::RemoteAPI
 
   # @group Logging in/out
 
-  # @todo change method name to #login! since we are changing internal state?
+  ##
   # The first method to call; other methods will fail until you are logged in.
+  #
   # @param [String] user JIRA user name to login with
   # @param [String] password
-  # @return [Boolean] true if successful
+  # @return [String] auth_token if successful, otherwise raises an exception
   def login username, password
-    response    = build 'login', username, password
-    @auth_token = response.document.xpath('//loginReturn').first.to_s
-    @user       = user
-    true
+    response        = soap_call 'login', username, password
+    self.auth_token = response.first.content
+    @user           = user
+    self.auth_token
   end
+  alias_method :log_in, :login
 
-  # @todo change method name to #logout! since we are changing internal state?
+  ##
   # You only need to call this to make an explicit logout; normally, a session
   # will automatically expire after a set time (configured on the server).
   # @return [Boolean] true if successful, otherwise false
   def logout
-    call( 'logout' ).to_boolean
+    jira_call( 'logout' ).to_boolean
   end
+  alias_method :log_out, :logout
 
   # @endgroup
 
 
   private
 
+  # XPath constant to get a node containing a response data.
+  RESPONSE_XPATH = '/node()[1]/node()[1]/node()[1]/node()[2]'.freeze
+
+  ##
   # @todo make this method less ugly
-  # @todo double check the return type
+  # @todo handle arrays of strings
+  #
   # A generic method for calling a SOAP method and soapifying all
-  # the arguments, adapted for usage with jiraSOAP.
-  # @param [String] method
-  # @param [Object] *args
+  # the arguments.
+  #
+  # @param [String] method name of the JIRA SOAP API method
+  # @param [Object] *args the arguments for the method, excluding the
+  #   authentication token
   # @return [Handsoap::Response]
   def build method, *args
     invoke "soap:#{method}" do |msg|
       for i in 0...args.size
-        arg = args.shift
-        case arg
+        case arg = args.shift
         when JIRA::Entity
           msg.add "soap:in#{i}", do |submsg| arg.soapify_for submsg end
         else
@@ -82,27 +81,34 @@ module RemoteAPI
     end
   end
 
-  # @todo find a less blunt XPath expression
+  # @return [Nokogiri::XML::NodeSet]
+  def soap_call method, *args
+    response = build method, *args
+    response .document.element/RESPONSE_XPATH
+  end
+
+  ##
   # A simple call, for methods that will return a single object.
+  #
   # @param [String] method
   # @param [Object] *args
-  # @return [Handsoap::XmlQueryFront::NodeSelection]
-  def call method, *args
-    response = build method, @auth_token, *args
-    response .document.xpath "//#{method}Return"
+  # @return [Nokogiri::XML::Element]
+  def jira_call method, *args
+    response = soap_call method, self.auth_token, *args
+    response.first
   end
 
+  ##
   # A more complex form of {#call} that does a little more work for
   # you when you need to build an array of return values.
-  # @param [String] method
-  # @param [Object] *args
-  # @return [Handsoap::XmlQueryFront::NodeSelection]
-  def jira_call type, method, *args
-    response = build method, @auth_token, *args
-    frags    = response.document.xpath("#{RESPONSE_XPATH}/#{method}Return")
-    frags.map { |frag| type.new_with_xml frag }
+  #
+  # @param [String] method name of the JIRA SOAP API method
+  # @param [Object] *args the arguments for the method, excluding the
+  #   authentication token
+  # @return [Nokogiri::XML::NodeSet]
+  def array_jira_call type, method, *args
+    response = soap_call method, self.auth_token, *args
+    response.xpath("node()").map { |frag| type.new_with_xml(frag) }
   end
 
 end
-
-end