jiraSOAP 0.7.1 → 0.8.0

data/lib/jiraSOAP/api/additions.rb

@@ -1,12 +1,13 @@
-module JIRA
-
+##
 # Methods declared here do not directly map to methods defined in JIRA's
 # SOAP API javadoc. They are generally close to something from the javadoc
 # but with some extra conveniences.
-module RemoteAPIAdditions
+module JIRA::RemoteAPIAdditions
 
+  ##
   # Returns the first field that exactly matches the given
   # name, otherwise returns nil.
+  #
   # @param [String] name
   # @return [JIRA::Field,nil]
   def get_custom_field_with_name name
@@ -16,7 +17,4 @@ module RemoteAPIAdditions
     nil
   end
 
-  # @todo a method for getting attachments
-end
-
 end

data/lib/jiraSOAP/api/attachments.rb

@@ -1,22 +1,34 @@
-module JIRA
-module RemoteAPI
-  # @group Working with issue Attachments and their metadata
+module JIRA::RemoteAPI
 
+  ##
+  # @note The JIRA SOAP API only works with the metadata for attachments,
+  #       you will have to look at your servers configuration to figure
+  #       out the proper URL to call to get attachment data.
+  #
+  # This module has implemented all relevant APIs as of JIRA 4.2.
+
+  # @group Attachments
+
+  ##
   # @todo change method name to reflect that you only get metadata
+  #
   # @param [String] issue_key
   # @return [Array<JIRA::AttachmentMetadata>]
-  def get_attachments_for_issue_with_key issue_key
-    jira_call JIRA::AttachmentMetadata, 'getAttachmentsFromIssue', issue_key
+  def attachments_for_issue_with_key issue_key
+    array_jira_call JIRA::AttachmentMetadata, 'getAttachmentsFromIssue', issue_key
   end
+  alias_method :get_attachments_for_issue_with_key, :attachments_for_issue_with_key
 
+  ##
   # Expect this method to be slow.
+  #
   # @param [String] issue_key
   # @param [Array<String>] filenames names to put on the files
   # @param [Array<String>] data base64 encoded data
   # @return [Boolean] true if successful
   def add_base64_encoded_attachments_to_issue_with_key issue_key, filenames, data
     invoke('soap:addBase64EncodedAttachmentsToIssue') { |msg|
-      msg.add 'soap:in0', @auth_token
+      msg.add 'soap:in0', self.auth_token
       msg.add 'soap:in1', issue_key
       msg.add 'soap:in2' do |submsg|
         filenames.each { |filename| submsg.add 'filenames', filename }
@@ -28,6 +40,4 @@ module RemoteAPI
     true
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/avatars.rb

@@ -1,45 +1,58 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Avatars
+module JIRA::RemoteAPI
 
+  # @group Avatars
+
+  ##
   # Gets 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
-    JIRA::Avatar.new_with_xml call( 'getProjectAvatar', project_key ).first
+  def project_avatar_for_key project_key
+    JIRA::Avatar.new_with_xml jira_call( 'getProjectAvatar', project_key )
   end
+  alias_method :get_project_avatar_for_key, :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 [Array<JIRA::Avatar>]
-  def get_project_avatars_for_key project_key, include_default_avatars = false
-    jira_call JIRA::Avatar, 'getProjectAvatars', project_key, include_default_avatars
+  def project_avatars_for_key project_key, include_default_avatars = false
+    array_jira_call JIRA::Avatar, 'getProjectAvatars', project_key, include_default_avatars
   end
+  alias_method :get_project_avatars_for_key, :project_avatars_for_key
 
-  # @note You cannot delete system avatars
-  # @note You need project administration permissions to delete an avatar
+  ##
+  # @note You cannot delete system avatars, and you need project
+  #       administration permissions to delete other avatars.
+  #
   # @param [String] avatar_id
   # @return [Boolean] true if successful
   def delete_project_avatar_with_id avatar_id
-    call 'deleteProjectAvatar', avatar_id
+    jira_call 'deleteProjectAvatar', avatar_id
     true
   end
 
-  # @note You need project administration permissions to edit an avatar
-  # @note JIRA does not care if the avatar_id is valid
+  ##
+  # @note You need project administration permissions to edit an avatar.
+  # @note JIRA does not care if the avatar_id is valid.
+  #
   # Change the project avatar to another existing avatar. If you want to
   # upload a new avatar and set it to be the new project avatar use
   # {#set_new_project_avatar_for_project_with_key} instead.
+  #
   # @return [Boolean] true if successful
   def set_project_avatar_for_project_with_key project_key, avatar_id
-    call 'setProjectAvatar', project_key, avatar_id
+    jira_call 'setProjectAvatar', project_key, avatar_id
     true
   end
 
-  # @note You need project administration permissions to edit an avatar
+  ##
+  # @note You need project administration permissions to edit an avatar.
+  #
   # Use this method to create a new custom avatar for a project and set it
   # to be current avatar for the project.
   #
@@ -48,17 +61,17 @@ module RemoteAPI
   # then it will be upscaled to 48 pixels.
   # The small version of the avatar image (16 pixels) is generated
   # automatically.
+  #
   # If you want to switch a project avatar to an avatar that already exists on
   # the system then use {#set_project_avatar_for_project_with_key} instead.
+  #
   # @param [String] project_key
   # @param [String] mime_type
   # @param [String] base64_image
   # @return [Boolean] true if successful
   def set_new_project_avatar_for_project_with_key project_key, mime_type, base64_image
-    call 'setNewProjectAvatar', project_key, mime_type, base64_image
+    jira_call 'setNewProjectAvatar', project_key, mime_type, base64_image
     true
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/comments.rb

@@ -1,33 +1,38 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Comments
+module JIRA::RemoteAPI
+
+  # @group Comments
 
   # @param [String] issue_key
   # @param [JIRA::Comment] comment
   # @return [Boolean] true if successful
   def add_comment_to_issue_with_key issue_key, comment
-    call 'addComment', issue_key, comment
+    jira_call 'addComment', issue_key, comment
     true
   end
 
   # @param [String] id
   # @return [JIRA::Comment]
-  def get_comment_with_id id
-    JIRA::Comment.new_with_xml call( 'getComment', id ).first
+  def comment_with_id id
+    JIRA::Comment.new_with_xml jira_call( 'getComment', id )
   end
+  alias_method :get_comment_with_id, :comment_with_id
 
   # @param [String] issue_key
   # @return [Array<JIRA::Comment>]
-  def get_comments_for_issue_with_key issue_key
-    jira_call JIRA::Comment, 'getComments', issue_key
+  def comments_for_issue_with_key issue_key
+    array_jira_call JIRA::Comment, 'getComments', issue_key
   end
+  alias_method :get_comments_for_issue_with_key, :comments_for_issue_with_key
 
   # @param [JIRA::Comment] comment
   # @return [JIRA::Comment]
   def update_comment comment
-    JIRA::Comment.new_with_xml call( 'editComment', comment ).first
+    JIRA::Comment.new_with_xml jira_call( 'editComment', comment )
+  end
+
+  # @param [JIRA::Comment]
+  def permission_to_edit_comment? comment
+    jira_call( 'hasPermissionToEditComment', comment ).to_boolean
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/filters.rb

@@ -1,20 +1,23 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Filters
+module JIRA::RemoteAPI
 
+  # @group Filters
+
+  ##
   # Retrieves favourite filters for the currently logged in user.
+  #
   # @return [Array<JIRA::Filter>]
-  def get_favourite_filters
-    jira_call JIRA::Filter, 'getFavouriteFilters'
+  def favourite_filters
+    array_jira_call JIRA::Filter, 'getFavouriteFilters'
   end
-  alias_method :get_favorite_filters, :get_favourite_filters
+  alias_method :get_favourite_filters, :favourite_filters
+  alias_method :get_favorite_filters,  :favourite_filters
+  alias_method :favorite_filters,      :favourite_filters
 
   # @param [String] id
   # @return [Fixnum]
-  def get_issue_count_for_filter_with_id id
-    call( 'getIssueCountForFilter', id ).to_i
+  def issue_count_for_filter_with_id id
+    jira_call( 'getIssueCountForFilter', id ).to_i
   end
+  alias_method :get_issue_count_for_filter_with_id, :issue_count_for_filter_with_id
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/issue_data_types.rb

@@ -1,51 +1,59 @@
-module JIRA
-module RemoteAPI
-  # @group Working with issue attributes
+module JIRA::RemoteAPI
+
+  # @group Issue attributes
 
   # @return [Array<JIRA::Priority>]
-  def get_priorities
-    jira_call JIRA::Priority, 'getPriorities'
+  def priorities
+    array_jira_call JIRA::Priority, 'getPriorities'
   end
+  alias_method :get_priorities, :priorities
 
   # @return [Array<JIRA::Resolution>]
-  def get_resolutions
-    jira_call JIRA::Resolution, 'getResolutions'
+  def resolutions
+    array_jira_call JIRA::Resolution, 'getResolutions'
   end
+  alias_method :get_resolutions, :resolutions
 
   # @return [Array<JIRA::Field>]
-  def get_custom_fields
-    jira_call JIRA::Field, 'getCustomFields'
+  def custom_fields
+    array_jira_call JIRA::Field, 'getCustomFields'
   end
+  alias_method :get_custom_fields, :custom_fields
 
   # @return [Array<JIRA::IssueType>]
-  def get_issue_types
-    jira_call JIRA::IssueType, 'getIssueTypes'
+  def issue_types
+    array_jira_call JIRA::IssueType, 'getIssueTypes'
   end
+  alias_method :get_issue_types, :issue_types
 
   # @return [Array<JIRA::Status>]
-  def get_statuses
-    jira_call JIRA::Status, 'getStatuses'
+  def statuses
+    array_jira_call JIRA::Status, 'getStatuses'
   end
+  alias_method :get_statuses, :statuses
 
   # @return [Array<JIRA::IssueType>]
-  def get_subtask_issue_types
-    jira_call JIRA::IssueType, 'getSubTaskIssueTypes'
+  def subtask_issue_types
+    array_jira_call JIRA::IssueType, 'getSubTaskIssueTypes'
   end
+  alias_method :get_subtask_issue_types, :subtask_issue_types
 
   # @param [String] project_id
   # @return [Array<JIRA::IssueType>]
-  def get_subtask_issue_types_for_project_with_id project_id
-    jira_call JIRA::IssueType, 'getSubTaskIssueTypesForProject', project_id
+  def subtask_issue_types_for_project_with_id project_id
+    array_jira_call JIRA::IssueType, 'getSubTaskIssueTypesForProject', project_id
   end
+  alias_method :get_subtask_issue_types_for_project_with_id, :subtask_issue_types_for_project_with_id
 
-  # I have no idea what this method does.
+  ##
   # @todo find out what this method does
+  #
+  # I have no idea what this method does.
+  #
   # @return [Boolean] true if no exceptions were raised
   def refresh_custom_fields
-    call 'refreshCustomFields'
+    jira_call 'refreshCustomFields'
     true
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/issues.rb

@@ -1,57 +1,68 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Issues
+module JIRA::RemoteAPI
 
+  # @group Issues
+
+  ##
   # This method is the equivalent of making an advanced search from the
   # web interface.
   #
   # During my own testing, I found that HTTP requests could timeout for really
-  # large requests (~2500 results). So I set a more reasonable upper limit;
-  # feel free to override it, but be aware of the potential issues.
+  # large requests (~2500 results) if you are not on the same network. So I set
+  # a more reasonable upper limit; feel free to override it, but be aware of
+  # the potential issues.
+  #
+  # The {JIRA::Issue} structure does not include any comments or attachments.
   #
-  # The JIRA::Issue structure does not include any comments or attachments.
   # @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
+  #   the value may be overridden by the server if max_results is too large
   # @return [Array<JIRA::Issue>]
-  def get_issues_from_jql_search jql_query, max_results = 2000
-    jira_call JIRA::Issue, 'getIssuesFromJqlSearch', jql_query, max_results
+  def issues_from_jql_search jql_query, max_results = 2000
+    array_jira_call JIRA::Issue, 'getIssuesFromJqlSearch', jql_query, max_results
   end
+  alias_method :get_issues_from_jql_search, :issues_from_jql_search
 
+  ##
   # 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).
+  # 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_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.
+  # 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', ['My new summary']
+  #  summary      = JIRA::FieldValue.new 'summary', ['My new summary']
   # @example Usage With A Custom Field
-  #  custom_field        = JIRA::FieldValue.new 'customfield_10060', ['123456']
+  #  custom_field = JIRA::FieldValue.new 'customfield_10060', ['123456']
   # @example Setting a field to be blank/nil
-  #  description = JIRA::FieldValue.new '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
   # @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
+      msg.add 'soap:in0', self.auth_token
       msg.add 'soap:in1', issue_key
       msg.add 'soap:in2' do |submsg|
         field_values.each { |fv| fv.soapify_for submsg }
       end
     }
-    JIRA::Issue.new_with_xml response.document.xpath('//updateIssueReturn').first
+    JIRA::Issue.new_with_xml response.document.element.xpath('//updateIssueReturn').first
   end
 
+  ##
   # Some fields will be ignored when an issue is created.
+  #
   #  - reporter - you cannot override this value at creation
   #  - resolution
   #  - attachments
@@ -59,44 +70,48 @@ module RemoteAPI
   #  - status
   #  - due date - I think this is a bug in jiraSOAP or JIRA
   #  - environment - I think this is a bug in jiraSOAP or JIRA
+  #
   # @param [JIRA::Issue] issue
   # @return [JIRA::Issue]
   def create_issue_with_issue issue
-    JIRA::Issue.new_with_xml call( 'createIssue', issue ).first
+    JIRA::Issue.new_with_xml jira_call( 'createIssue', issue )
   end
 
   # @param [String] issue_key
   # @return [JIRA::Issue]
-  def get_issue_with_key issue_key
-    JIRA::Issue.new_with_xml call( 'getIssue', issue_key ).first
+  def issue_with_key issue_key
+    JIRA::Issue.new_with_xml jira_call( 'getIssue', issue_key )
   end
+  alias_method :get_issue_with_key, :issue_with_key
 
   # @param [String] issue_id
   # @return [JIRA::Issue]
-  def get_issue_with_id issue_id
-    JIRA::Issue.new_with_xml call( 'getIssueById', issue_id ).first
+  def issue_with_id issue_id
+    JIRA::Issue.new_with_xml jira_call( 'getIssueById', issue_id )
   end
+  alias_method :get_issue_with_id, :issue_with_id
 
   # @param [String] id
   # @param [Fixnum] max_results
   # @param [Fixnum] offset
   # @return [Array<JIRA::Issue>]
-  def get_issues_from_filter_with_id id, max_results = 500, offset = 0
-    jira_call JIRA::Issue, 'getIssuesFromFilterWithLimit', id, offset, max_results
+  def issues_from_filter_with_id id, max_results = 500, offset = 0
+    array_jira_call JIRA::Issue, 'getIssuesFromFilterWithLimit', id, offset, max_results
   end
+  alias_method :get_issues_from_filter_with_id, :issues_from_filter_with_id
 
   # @param [String] issue_id
   # @return [Time]
-  def get_resolution_date_for_issue_with_id issue_id
-    call( 'getResolutionDateById', issue_id ).to_date
+  def resolution_date_for_issue_with_id issue_id
+    jira_call( 'getResolutionDateById', issue_id ).to_iso_date
   end
+  alias_method :get_resolution_date_for_issue_with_id, :resolution_date_for_issue_with_id
 
   # @param [String] issue_key
   # @return [Time]
-  def get_resolution_date_for_issue_with_key issue_key
-    call( 'getResolutionDateByKey', issue_key ).to_date
+  def resolution_date_for_issue_with_key issue_key
+    jira_call( 'getResolutionDateByKey', issue_key ).to_iso_date
   end
+  alias_method :get_resolution_date_for_issue_with_key, :resolution_date_for_issue_with_key
 
-  # @endgroup
-end
 end