jiraSOAP 0.1.1 → 0.1.2

data/README.markdown

@@ -50,20 +50,7 @@ Get the [Gist](http://gist.github.com/612186).
 Notes About Using This Gem
 --------------------------
 
-To get a reference for the API, you can look at the JavaDoc stuff provided by Atalssian [here](http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html).
-
-1. All method names have been made to feel more natural in a Ruby setting. Consult the `jiraSOAP` documentation for specifics.
-
-2. If an API call fails with a method missing error it is because the method has not been implement, yet. I started by implementing only the methods that I needed in order to port some old scripts that ran on jira4r; other methods will be added as them gem matures (or you could add it for me :D).
-
-3. URESOLVED issues have a Resolution with a value of `nil`.
-
-4. To empty a field (set it to nil) you can use this pattern:
-   jira.update_issue 'JIRA-1', JIRA::FieldValue.fieldValueWithNilValues 'description'
-
-5. Issue creation, using #create_issue_with_issue does not make use of all the fields in a JIRA::Issue. Which fields are used seems to depend on the version of JIRA you are connecting to.
-
-6. RemoteAPI#update_issue wants an id for each field that you pass it, but it really wants the name of the field that you want to update. See this [Gist](http://gist.github.com/612562).
+1. URESOLVED issues have a Resolution with a value of `nil`.
 
 
 TODO
@@ -71,11 +58,9 @@ TODO
 
 - 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
-- Documentation
 - Error handling
 - Finish implementing all of the API
 

data/lib/jiraSOAP/JIRAservice.rb

@@ -1,15 +1,33 @@
+# All the remote entities as well as the SOAP service client.
 module JIRA
+
+# Interface to the JIRA endpoint server; set at initialization.
+#
+# Due to limitations in Handsoap::Service, there can only be one endpoint.
+# You can have multiple instances of that one endpoint if you would
+# like; but if you try to set a differnt endpoint for a new instance you
+# will end up messing up any other instances currently being used.
+#
+# It is best to treat this class as a singleton. There should only be one.
+#
+# HTTPS is not supported in this version.
 class JIRAService < Handsoap::Service
   include RemoteAPI
 
   attr_reader :auth_token, :user
 
+  # Factory method to initialize and login.
+  #@param [String] url URL for the JIRA server
+  #@param [String] user JIRA user name to login with
+  #@param [String] password
   def self.instance_at_url(url, user, password)
     jira = JIRAService.new url
     jira.login user, password
     jira
   end
 
+  # Slightly hacky in order to set the endpoint at the initialization.
+  #@param endpoint_url URL for the JIRA server
   def initialize(endpoint_url)
     super
 
@@ -23,8 +41,10 @@ class JIRAService < Handsoap::Service
 
   #PONDER: a finalizer that will try to logout
 
+  # Something to help users out until the rest of the API is implemented.
   def method_missing(method, *args)
-    $stderr.puts "#{method} is not a defined method in the API...yet"
+    message  = 'Check the documentation; the method may not be implemented yet.'
+    raise NoMethodError, message, caller
   end
 
   protected

data/lib/jiraSOAP/handsoap_extensions.rb

@@ -1,14 +1,24 @@
-#PONDER: send upstream for consideration
+#Some simple extensions to Handsoap.
 module Handsoap
+#Some simple extensions to XmlMason. Currently, this only includes methods to
+#make it easier to build SOAP messages that contain arrays.
 module XmlMason
+  #Represents a node in an XML document
   class Node
-    #TODO: make recursive
+    #@todo Make this method recursive
+    #@param [String] node_name
+    #@param [Array] array
+    #@param [Hash] options
     def add_simple_array(node_name, array = [], options = {})
       prefix, name = parse_ns(node_name)
       node = append_child Element.new(self, prefix, name, nil, options)
       array.each { |element| node.add node_name, element }
     end
 
+    #@todo Make this method recursive
+    #@param [String] node_name
+    #@param [Array] array
+    #@param [Hash] options
     def add_complex_array(node_name, array = [], options = {})
       prefix, name = parse_ns(node_name)
       node = append_child Element.new(self, prefix, name, nil, options)

data/lib/jiraSOAP/remoteAPI.rb

@@ -1,18 +1,31 @@
+# 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 code refactoring and de-duplication
 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]'
 
+  #The first method to call. No other method will work unless you are logged in.
+  #@param [String] user JIRA user name to login with
+  #@param [String] password
+  #@return [boolean] true if successful, otherwise false
   def login(user, password)
     response = invoke('soap:login') { |msg|
       msg.add 'soap:in0', user
       msg.add 'soap:in1', password
     }
-    #TODO: error handling (catch the exception and look at the Response node?)
     #cache now that we know it is safe to do so
     @user       = user
     @auth_token = response.document.xpath('//loginReturn').first.to_s
     true
   end
 
+  #You only need to call this to make an exlicit logout; normally, a session
+  #willautomatically expire after a set time (configured on the server).
+  #@return [boolean] true if successful, otherwise false
   def logout
     response = invoke('soap:logout') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -20,6 +33,8 @@ module RemoteAPI
     response.document.xpath('//logoutReturn').first.to_s == 'true'
   end
 
+  #Get the global listing for types of priorities.
+  #@return [[JIRA::Priority]]
   def get_priorities
     response = invoke('soap:getPriorities') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -30,6 +45,8 @@ module RemoteAPI
     }
   end
 
+  #Get the global listing for types of resolutions.
+  #@return [[JIRA::Resolution]]
   def get_resolutions
     response = invoke('soap:getResolutions') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -40,6 +57,8 @@ module RemoteAPI
     }
   end
 
+  #Get the global listing for types of custom fields.
+  #@return [[JIRA::Field]]
   def get_custom_fields
     response = invoke('soap:getCustomFields') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -50,6 +69,8 @@ module RemoteAPI
     }
   end
 
+  #Get the global listing for types of issues.
+  #@return [[JIRA::IssueType]]
   def get_issue_types
     response = invoke('soap:getIssueTypes') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -60,6 +81,8 @@ module RemoteAPI
     }
   end
 
+  #Get the global listing of status type.
+  #@return [[JIRA::Status]]
   def get_statuses
     response = invoke('soap:getStatuses') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -70,6 +93,8 @@ module RemoteAPI
     }
   end
 
+  #Get the global listing for notification schemes.
+  #@return [[JIRA::Scheme]]
   def get_notification_schemes
     response = invoke('soap:getNotificationSchemes') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -80,6 +105,9 @@ module RemoteAPI
     }
   end
 
+  #Get all the versions associated with a project.
+  #@param [String] project_key
+  #@return [[JIRA::Version]]
   def get_versions_for_project(project_key)
     response = invoke('soap:getVersions') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -91,6 +119,9 @@ module RemoteAPI
     }
   end
 
+  #Get the information for a project with a given key.
+  #@param [String] project_key
+  #@return [JIRA::Project]
   def get_project_with_key(project_key)
     response = invoke('soap:getProjectByKey') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -100,6 +131,9 @@ module RemoteAPI
     JIRA::Project.project_with_xml_fragment frag
   end
 
+  #This will only give you basic information about a user.
+  #@param [String] user_name
+  #@return [JIRA::User]
   def get_user_with_name(user_name)
     response = invoke('soap:getUser') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -108,6 +142,10 @@ module RemoteAPI
     JIRA::User.user_with_xml_fragment response.document.xpath '//getUserReturn'
   end
 
+  #Gives you the default avatar image for a project; if you want all
+  #the avatars for a project, use {#get_project_avatars_for_key}.
+  #@param [String] project_key
+  #@return [JIRA::Avatar]
   def get_project_avatar_for_key(project_key)
     response = invoke('soap:getProjectAvatar') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -116,6 +154,27 @@ module RemoteAPI
     JIRA::Avatar.avatar_with_xml_fragment response.document.xpath '//getProjectAvatarReturn'
   end
 
+  #Gives ALL avatars for a given project use this method; if you
+  #just want the default avatar, use {#get_project_avatar_for_key}.
+  #@param [String] project_key
+  #@return [[JIRA::Avatar]]
+  def get_project_avatars_for_key(project_key)
+    response = invoke('soap:getProjectAvatars') { |msg|
+      msg.add 'soap:in0', @auth_token
+      msg.add 'soap:in1', project_key
+    }
+    response.document.xpath("#{RESPONSE_XPATH}/getProjectAvatarsReturn").map {
+      |frag|
+      JIRA::Avatar.avatar_with_xml_fragment frag
+    }
+  end
+
+  #This method is the equivalent of making an advanced search from the
+  #web interface.
+  #@param [String] jql_query JQL query as a string
+  #@param [Fixnum] max_results limit on number of returned results;
+  #  the value may be overridden by the server if max_results is too large
+  #@return [[JIRA::Issue]]
   def get_issues_from_jql_search(jql_query, max_results = 500)
     response = invoke('soap:getIssuesFromJqlSearch') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -128,6 +187,29 @@ module RemoteAPI
     }
   end
 
+  #This method can update most, but not all, issue fields.
+  #
+  #Fields known to not update via this method:
+  #  - status - use {#progress_workflow_action}
+  #  - attachments - use {#add_base64_encoded_attachment_to_issue}
+  #
+  #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']
+  #@example Usage With A Custom Field
+  #  custom_field        = JIRA::FieldValue.new
+  #  custom_field.id     = 'customfield_10060'
+  #  custom_field.values = ['123456']
+  #@example Setting a field to be blank/nil
+  #  description = JIRA::FieldValue.field_value_with_nil_values 'description'
+  #@example Calling the method to update an issue
+  #  jira_service_instance.update_issue 'PROJECT-1', description, custom_field
+  #@param [String] issue_key
+  #@param [JIRA::FieldValue] *field_values
+  #@return [JIRA::Issue]
   def update_issue(issue_key, *field_values)
     response = invoke('soap:updateIssue') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -140,6 +222,16 @@ module RemoteAPI
     JIRA::Issue.issue_with_xml_fragment frag
   end
 
+  #Some fields will be ignored when an issue is created:
+  #  - reporter - you cannot override this value at creation
+  #  - due date - I think this is a bug in jiraSOAP or JIRA
+  #  - attachments
+  #  - votes
+  #  - status
+  #  - resolution
+  #  - environment - I think this is a bug in jiraSOAP or JIRA
+  #@param [JIRA::Issue] issue
+  #@return [JIRA::Issue]
   def create_issue_with_issue(issue)
     response = invoke('soap:createIssue') { |msg|
       msg.add 'soap:in0', @auth_token
@@ -175,7 +267,6 @@ end
 # getIssuesFromFilterWithLimit
 # getIssuesFromTextSearchWithLimit
 # getIssueTypesForProject
-# getProjectAvatars
 # getProjectById
 # getServerInfo
 # getSubTaskIssueTypes

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Mark Rada