jiraSOAP 0.4.0 → 0.5.0

data/ChangeLog

@@ -0,0 +1,17 @@
+Version 0.5
+
+	* Begin summarizing changes in a changelog
+	* Begin abstracting parts of JIRA model
+
+	* Fixed RemoteAPI#add_version_to_project_with_key
+
+	* Added RemoteAPI#get_server_configuration
+
+	* Changed use of factories to constructors in the model
+	* Changed FieldValue#id to FieldValue#field_name
+	* Changed CustomField to CustomFieldValue
+	* Changed User#name to User#username
+	* Changed Scheme#type to return the class name
+	* Changed some RemoteAPI method names to be more descriptive
+	* Changed Avatar#content_type to Avatar#mime_type
+	* Various documentation updates

data/LICENSE

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

data/README.markdown

@@ -3,6 +3,8 @@ 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.
 
+Read the documentation [here](http://rdoc.info/github/Marketcircle/jiraSOAP/master/frames). The meat of the service is in the `RemoteAPI` module.
+
 
 Motivation
 ----------
@@ -18,6 +20,7 @@ Pick up where `jira4r` left off:
 - Implement the current API; `jira4r` does not implement APIs from 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 is so terse
 
 
 Getting Started
@@ -44,22 +47,16 @@ Once that ugliness is over with, you can run a quick demo (making appropriate su
 
      db.logout
 
-Get the [Gist](http://gist.github.com/612186).
-
-Read the documentation [here](http://rdoc.info/github/Marketcircle/jiraSOAP/master/frames). The meat of the service is in the `RemoteAPI` module.
-
 
 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)
-- Refactor for a smaller code base
-- Fix type hacks;. dates should be `NSDate`s and URLs should be `NSURL`s, right now they are all strings
 - Public test suite
   + Needs a mock server
-- Error handling
-- Finish implementing all of the API
 
 
 Note on Patches/Pull Requests

data/lib/jiraSOAP.rb

@@ -7,10 +7,10 @@ Handsoap.http_driver = :net_http
 
 require 'jiraSOAP/url.rb'
 require 'jiraSOAP/handsoap_extensions.rb'
-require 'jiraSOAP/remoteEntities.rb'
-require 'jiraSOAP/remoteAPI.rb'
+require 'jiraSOAP/entities.rb'
+require 'jiraSOAP/api.rb'
 
 require 'jiraSOAP/JIRAservice.rb'
 
 #overrides and additions
-require 'lib/macruby_stuff.rb' if RUBY_ENGINE == 'macruby'
+require 'lib/jiraSOAP/macruby_bonuses.rb' if RUBY_ENGINE == 'macruby'

data/lib/jiraSOAP/JIRAservice.rb

@@ -20,9 +20,13 @@ class JIRAService < Handsoap::Service
 
   # @return [String]
   attr_reader :auth_token
+
   # @return [String]
   attr_reader :user
 
+  # @return [String]
+  attr_reader :endpoint_url
+
   # Factory method to initialize and login.
   # @param [String] url URL for the JIRA server
   # @param [String] user JIRA user name to login with
@@ -37,8 +41,6 @@ class JIRAService < Handsoap::Service
   # Slightly hacky in order to set the endpoint at the initialization.
   # @param endpoint_url URL for the JIRA server
   def initialize(endpoint_url)
-    super
-
     @endpoint_url = endpoint_url
     endpoint_data = {
       :uri => "#{endpoint_url}/rpc/soap/jirasoapservice-v2",
@@ -52,8 +54,9 @@ class JIRAService < Handsoap::Service
   def method_missing(method, *args)
     message  = "#{method} is not a valid method. Check the documentation; the "
     message << 'method may not be implemented or has changed in recent '
-    message << 'revisions. The client side API has not been stabilized yet.'
-    raise NoMethodError, message, caller
+    message << 'revisions. The API has not been stabilized yet.'
+    STDERR.puts message
+    super method, *args
   end
 
   protected

data/lib/jiraSOAP/{remoteAPI.rb → api.rb}

@@ -1,7 +1,15 @@
 # Contains the API defined by Atlassian for the JIRA SOAP service. The JavaDoc
 # for the SOAP API is located at http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html.
 # @todo exception handling
+# @todo logging
 # @todo code refactoring and de-duplication
+# @todo break the API down by task, like Apple's developer documentation
+# @todo deleteProjectAvatar [target v0.5]
+# @todo setProjectAvatar (change to different existing) [target v0.5]
+# @todo setNewProjectAvatar (upload new and set it) [target v0.5]
+# @todo createProjectRole [v0.6]
+# @todo getAvailableActions [target v0.7]
+# @todo progressWorkflowAction [target v0.7]
 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
@@ -11,7 +19,7 @@ module RemoteAPI
   # 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 [true] true if successful, otherwise an exception is thrown
+  # @return [boolean] true if successful, otherwise an exception is thrown
   def login(user, password)
     response = invoke('soap:login') { |msg|
       msg.add 'soap:in0', user
@@ -25,12 +33,12 @@ module RemoteAPI
 
   # 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 [true] true if successful, otherwise false
+  # @return [boolean] true if successful, otherwise false
   def logout
     response = invoke('soap:logout') { |msg|
       msg.add 'soap:in0', @auth_token
     }
-    response.document.xpath('//logoutReturn').first.to_s == 'true'
+    response.document.xpath('//logoutReturn').to_boolean
   end
 
   # @return [[JIRA::Priority]]
@@ -39,8 +47,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getPrioritiesReturn").map {
-      |frag|
-      JIRA::Priority.priority_with_xml_fragment frag
+      |frag| JIRA::Priority.new_with_xml_fragment frag
     }
   end
 
@@ -50,8 +57,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getResolutionsReturn").map {
-      |frag|
-      JIRA::Resolution.resolution_with_xml_fragment frag
+      |frag| JIRA::Resolution.new_with_xml_fragment frag
     }
   end
 
@@ -61,8 +67,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getCustomFieldsReturn").map {
-      |frag|
-      JIRA::Field.field_with_xml_fragment frag
+      |frag| JIRA::Field.new_with_xml_fragment frag
     }
   end
 
@@ -72,8 +77,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getIssueTypesReturn").map {
-      |frag|
-      JIRA::IssueType.issue_type_with_xml_fragment frag
+      |frag| JIRA::IssueType.new_with_xml_fragment frag
     }
   end
 
@@ -83,19 +87,17 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getStatusesReturn").map {
-      |frag|
-      JIRA::Status.status_with_xml_fragment frag
+      |frag| JIRA::Status.new_with_xml_fragment frag
     }
   end
 
-  # @return [[JIRA::Scheme]]
+  # @return [[JIRA::NotificationScheme]]
   def get_notification_schemes
     response = invoke('soap:getNotificationSchemes') { |msg|
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getNotificationSchemesReturn").map {
-      |frag|
-      JIRA::Scheme.scheme_with_xml_fragment frag
+      |frag| JIRA::NotificationScheme.new_with_xml_fragment frag
     }
   end
 
@@ -107,11 +109,13 @@ module RemoteAPI
       msg.add 'soap:in1', project_key
     }
     response.document.xpath("#{RESPONSE_XPATH}/getVersionsReturn").map {
-      |frag|
-      JIRA::Version.version_with_xml_fragment frag
+      |frag| JIRA::Version.new_with_xml_fragment frag
     }
   end
 
+  # You need to explicitly ask for schemes in order to get them. By
+  # default, most project fetching methods purposely leave out all
+  # the scheme information as permission schemes can be very large.
   # @param [String] project_key
   # @return [JIRA::Project]
   def get_project_with_key(project_key)
@@ -119,8 +123,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', project_key
     }
-    frag = response.document.xpath '//getProjectByKeyReturn'
-    JIRA::Project.project_with_xml_fragment frag
+    JIRA::Project.new_with_xml_fragment response.document.xpath('//getProjectByKeyReturn').first
   end
 
   # @param [String] user_name
@@ -130,7 +133,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', user_name
     }
-    JIRA::User.user_with_xml_fragment response.document.xpath '//getUserReturn'
+    JIRA::User.new_with_xml_fragment response.document.xpath('//getUserReturn').first
   end
 
   # Gets you the default avatar image for a project; if you want all
@@ -142,11 +145,11 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', project_key
     }
-    JIRA::Avatar.avatar_with_xml_fragment response.document.xpath '//getProjectAvatarReturn'
+    JIRA::Avatar.new_with_xml_fragment response.document.xpath('//getProjectAvatarReturn').first
   end
 
-  # Gets ALL avatars for a given project use this method; if you
-  # just want the default avatar, use {#get_project_avatar_for_key}.
+  # Gets ALL avatars for a given project with this method; if you
+  # just want the project avatar, use {#get_project_avatar_for_key}.
   # @param [String] project_key
   # @param [boolean] include_default_avatars
   # @return [[JIRA::Avatar]]
@@ -157,8 +160,7 @@ module RemoteAPI
       msg.add 'soap:in2', include_default_avatars
     }
     response.document.xpath("#{RESPONSE_XPATH}/getProjectAvatarsReturn").map {
-      |frag|
-      JIRA::Avatar.avatar_with_xml_fragment frag
+      |frag| JIRA::Avatar.new_with_xml_fragment frag
     }
   end
 
@@ -181,29 +183,27 @@ module RemoteAPI
       msg.add 'soap:in2', max_results
     }
     response.document.xpath("#{RESPONSE_XPATH}/getIssuesFromJqlSearchReturn").map {
-      |frag|
-      JIRA::Issue.issue_with_xml_fragment frag
+      |frag| JIRA::Issue.new_with_xml_fragment frag
     }
   end
 
-  # This method can update most, but not all, issue fields.
+  # This method can update most, but not all, issue fields. Some limitations
+  # are because of how the API is designed, and some are because I have not
+  # yet implemented the ability to update fields made of custom objects (things
+  # in the JIRA module).
   #
   # Fields known to not update via this method:
   #  - status - use {#progress_workflow_action}
-  #  - attachments - use {#add_base64_encoded_attachment_to_issue}
+  #  - attachments - use {#add_base64_encoded_attachments_to_issue_with_key}
   #
   # Though JIRA::FieldValue objects have an id field, they do not expect to be
   # given id values. You must use the name of the field you wish to update.
   # @example Usage With A Normal Field
-  #  summary        = JIRA::FieldValue.new
-  #  summary.id     = 'summary'
-  #  summary.values = ['My new summary']
+  #  summary        = JIRA::FieldValue.new 'summary', ['My new summary']
   # @example Usage With A Custom Field
-  #  custom_field        = JIRA::FieldValue.new
-  #  custom_field.id     = 'customfield_10060'
-  #  custom_field.values = ['123456']
+  #  custom_field        = JIRA::FieldValue.new 'customfield_10060', ['123456']
   # @example Setting a field to be blank/nil
-  #  description = JIRA::FieldValue.field_value_with_nil_values 'description'
+  #  description = JIRA::FieldValue.new 'description'
   # @example Calling the method to update an issue
   #  jira_service_instance.update_issue 'PROJECT-1', description, custom_field
   # @param [String] issue_key
@@ -217,8 +217,7 @@ module RemoteAPI
         field_values.each { |fv| fv.soapify_for submsg }
       end
     }
-    frag = response.document.xpath '//updateIssueReturn'
-    JIRA::Issue.issue_with_xml_fragment frag
+    JIRA::Issue.new_with_xml_fragment response.document.xpath('//updateIssueReturn').first
   end
 
   # Some fields will be ignored when an issue is created.
@@ -238,8 +237,7 @@ module RemoteAPI
         issue.soapify_for submsg
       end
     }
-    frag = response.document.xpath '//createIssueReturn'
-    JIRA::Issue.issue_with_xml_fragment frag
+    JIRA::Issue.new_with_xml_fragment response.document.xpath('//createIssueReturn').first
   end
 
   # @param [String] issue_key
@@ -249,8 +247,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', issue_key
     }
-    frag = response.document.xpath '//getIssueReturn'
-    JIRA::Issue.issue_with_xml_fragment frag
+    JIRA::Issue.new_with_xml_fragment response.document.xpath('//getIssueReturn').first
   end
 
   # @param [String] issue_id
@@ -260,8 +257,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', issue_id
     }
-    frag = response.document.xpath '//getIssueByIdReturn'
-    JIRA::Issue.issue_with_xml_fragment frag
+    JIRA::Issue.new_with_xml_fragment response.document.xpath('//getIssueByIdReturn').first
   end
 
   # @param [String] issue_key
@@ -272,8 +268,7 @@ module RemoteAPI
       msg.add 'soap:in1', issue_key
     }
     response.document.xpath("#{RESPONSE_XPATH}/getAttachmentsFromIssueReturn").map {
-      |frag|
-      JIRA::AttachmentMetadata.attachment_with_xml_fragment frag
+      |frag| JIRA::AttachmentMetadata.new_with_xml_fragment frag
     }
   end
 
@@ -289,14 +284,13 @@ module RemoteAPI
   # @param [String] project_key
   # @param [JIRA::Version] version
   # @return [JIRA::Version]
-  def add_version_to_project(project_key, version)
+  def add_version_to_project_with_key(project_key, version)
     response = invoke('soap:addVersion') { |msg|
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', project_key
       msg.add 'soap:in2' do |submsg| version.soapify_for submsg end
     }
-    frag = response.document.xpath '//addVersionReturn'
-    JIRA::Version.version_with_xml_fragment frag
+    JIRA::Version.new_with_xml_fragment response.document.xpath('//addVersionReturn').first
   end
 
   # The archive state can only be set to true for versions that have not been
@@ -326,8 +320,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1' do |submsg| project.soapify_for submsg end
     }
-    frag = response.document.xpath '//createProjectFromObjectReturn'
-    JIRA::Project.project_with_xml_fragment frag
+    JIRA::Project.new_with_xml_fragment response.document.xpath('//createProjectFromObjectReturn').first
   end
 
   # You can set the release state for a project with this method.
@@ -352,8 +345,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1' do |submsg| project.soapify_for submsg end
     }
-    frag = response.document.xpath '//updateProjectReturn'
-    JIRA::Project.project_with_xml_fragment frag
+    JIRA::Project.new_with_xml_fragment response.document.xpath('//updateProjectReturn').first
   end
 
   # It seems that creating a user without any permission groups will trigger
@@ -374,8 +366,7 @@ module RemoteAPI
       msg.add 'soap:in3', full_name
       msg.add 'soap:in4', email
     }
-    frag = response.document.xpath '//createUserReturn'
-    JIRA::User.user_with_xml_fragment frag
+    JIRA::User.new_with_xml_fragment response.document.xpath('//createUserReturn').first
   end
 
   # @param [String] username
@@ -395,8 +386,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', project_id
     }
-    frag = response.document.xpath '//getProjectByIdReturn'
-    JIRA::Project.project_with_xml_fragment frag
+    JIRA::Project.new_with_xml_fragment response.document.xpath('//getProjectByIdReturn').first
   end
 
   # @todo parse the permission scheme
@@ -408,8 +398,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', project_id
     }
-    frag = response.document.xpath '//getProjectWithSchemesByIdReturn'
-    JIRA::Project.project_with_xml_fragment frag
+    JIRA::Project.new_with_xml_fragment response.document.xpath('//getProjectWithSchemesByIdReturn').first
   end
 
   # @param [String] issue_key
@@ -431,8 +420,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', id
     }
-    frag = response.document.xpath '//getCommentReturn'
-    JIRA::Comment.comment_with_xml_fragment frag
+    JIRA::Comment.new_with_xml_fragment response.document.xpath('//getCommentReturn').first
   end
 
   # @param [String] issue_key
@@ -443,8 +431,7 @@ module RemoteAPI
       msg.add 'soap:in1', issue_key
     }
     response.document.xpath("#{RESPONSE_XPATH}/getCommentsReturn").map {
-      |frag|
-      JIRA::Comment.comment_with_xml_fragment frag
+      |frag| JIRA::Comment.new_with_xml_fragment frag
     }
   end
 
@@ -456,8 +443,7 @@ module RemoteAPI
       msg.add 'soap:in1', project_id
     }
     response.document.xpath("#{RESPONSE_XPATH}/getIssueTypesForProjectReturn").map {
-      |frag|
-      JIRA::IssueType.issue_type_with_xml_fragment frag
+      |frag| JIRA::IssueType.new_with_xml_fragment frag
     }
   end
 
@@ -475,8 +461,7 @@ module RemoteAPI
       msg.add 'soap:in3', max_results
     }
     response.document.xpath("#{RESPONSE_XPATH}/getIssuesFromTextSearchWithLimitReturn").map {
-     |frag|
-      JIRA::Issue.issue_with_xml_fragment frag
+     |frag| JIRA::Issue.new_with_xml_fragment frag
     }
   end
 
@@ -487,8 +472,8 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1' do |submsg| comment.soapify_for submsg end
     }
-    frag = response.document.xpath '//editCommentReturn'
-    JIRA::Comment.comment_with_xml_fragment frag
+    frag = response.document.xpath('//editCommentReturn').first
+    JIRA::Comment.new_with_xml_fragment frag
   end
 
   # @return [[JIRA::IssueType]]
@@ -497,8 +482,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getSubTaskIssueTypesReturn").map {
-      |frag|
-      JIRA::IssueType.issue_type_with_xml_fragment frag
+      |frag| JIRA::IssueType.new_with_xml_fragment frag
     }
   end
 
@@ -510,8 +494,7 @@ module RemoteAPI
       msg.add 'soap:in1', project_id
     }
     response.document.xpath("#{RESPONSE_XPATH}/getSubtaskIssueTypesForProjectReturn").map {
-      |frag|
-      JIRA::IssueType.issue_type_with_xml_fragment frag
+      |frag| JIRA::IssueType.new_with_xml_fragment frag
     }
   end
 
@@ -532,8 +515,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
     }
     response.document.xpath("#{RESPONSE_XPATH}/getFavouriteFiltersReturn").map {
-      |frag|
-      JIRA::Filter.filter_with_xml_fragment frag
+      |frag| JIRA::Filter.new_with_xml_fragment frag
     }
   end
 
@@ -549,8 +531,7 @@ module RemoteAPI
       msg.add 'soap:in3', max_results
     }
     response.document.xpath("#{RESPONSE_XPATH}/getIssuesFromFilterWithLimitReturn").map {
-      |frag|
-      JIRA::Issue.issue_with_xml_fragment frag
+      |frag| JIRA::Issue.new_with_xml_fragment frag
     }
   end
 
@@ -561,7 +542,7 @@ module RemoteAPI
       msg.add 'soap:in0', @auth_token
       msg.add 'soap:in1', id
     }
-    response.document.xpath('//getIssueCountForFilterReturn').to_s.to_i
+    response.document.xpath('//getIssueCountForFilterReturn').to_i
   end
 
   # @todo optimize building the message, try a single pass
@@ -590,15 +571,14 @@ module RemoteAPI
     response = invoke('soap:getServerInfo') { |msg|
       msg.add 'soap:in0', @auth_token
     }
-    frag = response.document.xpath '//getServerInfoReturn'
-    JIRA::ServerInfo.server_info_with_xml_fragment frag
+    JIRA::ServerInfo.new_with_xml_fragment response.document.xpath('//getServerInfoReturn').first
   end
-end
 
-#TODO: v0.5
-# createProjectRole
-# deleteProjectAvatar
-# getAvailableActions
-# progressWorkflowAction
-# setProjectAvatar (change to different existing)
-# setNewProjectAvatar (upload new and set it)
+  # @return [JIRA::ServerConfiguration]
+  def get_server_configuration
+    response = invoke('soap:getConfiguration') { |msg|
+      msg.add 'soap:in0', @auth_token
+    }
+    JIRA::ServerConfiguration.new_with_xml_fragment response.document.xpath('//getConfigurationReturn').first
+  end
+end