jiraSOAP 0.7.1 → 0.8.0

data/lib/jiraSOAP/api/project_roles.rb

@@ -1,49 +1,56 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Project Roles
+module JIRA::RemoteAPI
+
+  # @group Project Roles
 
   # @return [Array<JIRA::ProjectRole>]
-  def get_project_roles
-    jira_call JIRA::ProjectRole, 'getProjectRoles'
+  def project_roles
+    array_jira_call JIRA::ProjectRole, 'getProjectRoles'
   end
+  alias_method :get_project_roles, :project_roles
 
   # @param [String] role_id
   # @return [JIRA::ProjectRole]
-  def get_project_role_with_id role_id
-    JIRA::ProjectRole.new_with_xml call( 'getProjectRole', role_id ).first
+  def project_role_with_id role_id
+    JIRA::ProjectRole.new_with_xml jira_call( 'getProjectRole', role_id )
   end
+  alias_method :get_project_role_with_id, :project_role_with_id
 
   # @param [JIRA::ProjectRole] project_role
   # @return [JIRA::ProjectRole] the role that was created
   def create_project_role_with_role project_role
-    JIRA::ProjectRole.new_with_xml call( 'createProjectRole', project_role ).first
+    JIRA::ProjectRole.new_with_xml jira_call( 'createProjectRole', project_role )
   end
 
+  ##
   # @note JIRA 4.0 and 4.2 returns an exception if the name already exists
+  #
   # Returns true if the name does not exist.
+  #
   # @param [String] project_role_name
   # @return [Boolean] true if successful
   def project_role_name_unique? project_role_name
-    call( 'isProjectRoleNameUnique', project_role_name ).to_boolean
+    jira_call( 'isProjectRoleNameUnique', project_role_name ).to_boolean
   end
 
-  # @note the confirm argument appears to do nothing (at least on JIRA 4.0)
+  ##
+  # @note The confirm argument appears to do nothing (at least on JIRA 4.0)
+  #
   # @param [JIRA::ProjectRole] project_role
   # @param [Boolean] confirm
   # @return [Boolean] true if successful
   def delete_project_role project_role, confirm = true
-    call 'deleteProjectRole', project_role, confirm
+    jira_call 'deleteProjectRole', project_role, confirm
     true
   end
 
+  ##
   # @note JIRA 4.0 will not update project roles, it will instead throw
-  #  an exception telling you that the project role already exists
+  #       an exception telling you that the project role already exists
+  #
   # @param [JIRA::ProjectRole] project_role
   # @return [JIRA::ProjectRole] the role after the update
   def update_project_role_with_role project_role
-    JIRA::ProjectRole.new_with_xml call( 'updateProjectRole', project_role ).first
+    JIRA::ProjectRole.new_with_xml jira_call( 'updateProjectRole', project_role )
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/projects.rb

@@ -1,67 +1,80 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Projects
+module JIRA::RemoteAPI
 
+  # @group Projects
+
+  ##
   # 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
-    JIRA::Project.new_with_xml call( 'getProjectByKey', project_key ).first
+  def project_with_key project_key
+    JIRA::Project.new_with_xml jira_call( 'getProjectByKey', project_key )
   end
+  alias_method :get_project_with_key, :project_with_key
 
+  ##
   # Requires you to set at least a project name, key, and lead.
   # However, it is also a good idea to set other project properties, such as
   # the permission scheme as the default permission scheme can be too
   # restrictive in most cases.
+  #
   # @param [JIRA::Project] project
   # @return [JIRA::Project]
   def create_project_with_project project
-    JIRA::Project.new_with_xml call( 'createProjectFromObject', project ).first
+    JIRA::Project.new_with_xml jira_call( 'createProjectFromObject', project )
   end
 
+  ##
   # The id of the project is the only field that you cannot update. Or, at
   # least the only field I know that you cannot update.
+  #
   # @param [JIRA::Project] project
   # @return [JIRA::Project]
   def update_project_with_project project
-    JIRA::Project.new_with_xml call( 'updateProject', project ).first
+    JIRA::Project.new_with_xml jira_call( 'updateProject', project )
   end
 
   # @param [String] project_id
   # @return [JIRA::Project]
-  def get_project_with_id project_id
-    JIRA::Project.new_with_xml call( 'getProjectById', project_id ).first
+  def project_with_id project_id
+    JIRA::Project.new_with_xml jira_call( 'getProjectById', project_id )
   end
+  alias_method :get_project_with_id, :project_with_id
 
-  # @todo parse the permission scheme
+  ##
+  # @todo Parse the permission scheme
   # @note This method does not yet include the permission scheme.
+  #
   # @param [String] project_id
   # @return [JIRA::Project]
-  def get_project_including_schemes_with_id project_id
-    JIRA::Project.new_with_xml call( 'getProjectWithSchemesById', project_id ).first
+  def project_including_schemes_with_id project_id
+    JIRA::Project.new_with_xml jira_call( 'getProjectWithSchemesById', project_id )
   end
+  alias_method :get_project_including_schemes_with_id, :project_including_schemes_with_id
 
   # @param [String] project_name
   # @return [Array<JIRA::IssueType>]
-  def get_issue_types_for_project_with_id project_id
-    jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
+  def issue_types_for_project_with_id project_id
+    array_jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
   end
+  alias_method :get_issue_types_for_project_with_id, :issue_types_for_project_with_id
 
-  # @note This will not fill in JIRA::Scheme data for the projects.
+  ##
+  # @note This will not fill in {JIRA::Scheme} data for the projects.
+  #
   # @return [Array<JIRA::Project>]
-  def get_projects_without_schemes
-    jira_call JIRA::Project, 'getProjectsNoSchemes'
+  def projects_without_schemes
+    array_jira_call JIRA::Project, 'getProjectsNoSchemes'
   end
+  alias_method :get_projects_without_schemes, :projects_without_schemes
 
   # @param [String] project_key
   # @return [Boolean] true if successful
   def delete_project_with_key project_key
-    call 'deleteProject', project_key
+    jira_call 'deleteProject', project_key
     true
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/schemes.rb

@@ -1,17 +1,17 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Schemes
+module JIRA::RemoteAPI
+
+  # @group Schemes
 
   # @return [Array<JIRA::NotificationScheme>]
-  def get_notification_schemes
-    jira_call JIRA::NotificationScheme, 'getNotificationSchemes'
+  def notification_schemes
+    array_jira_call JIRA::NotificationScheme, 'getNotificationSchemes'
   end
+  alias_method :get_notification_schemes, :notification_schemes
 
   # @return [Array<JIRA::PermissionScheme>]
-  def get_permission_schemes
-    jira_call JIRA::PermissionScheme, 'getPermissionSchemes'
+  def permission_schemes
+    array_jira_call JIRA::PermissionScheme, 'getPermissionSchemes'
   end
+  alias_method :get_permission_schemes, :permission_schemes
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/server_info.rb

@@ -1,18 +1,20 @@
-module JIRA
-module RemoteAPI
-  # @group Getting information about the server
+module JIRA::RemoteAPI
 
+  # @group Server Information
+
+  ##
   # The @build_date attribute is a Time value, but does not include a time.
+  #
   # @return [JIRA::ServerInfo]
-  def get_server_info
-    JIRA::ServerInfo.new_with_xml call( 'getServerInfo' ).first
+  def server_info
+    JIRA::ServerInfo.new_with_xml jira_call( 'getServerInfo' )
   end
+  alias_method :get_server_info, :server_info
 
   # @return [JIRA::ServerConfiguration]
-  def get_server_configuration
-    JIRA::ServerConfiguration.new_with_xml call( 'getConfiguration' ).first
+  def server_configuration
+    JIRA::ServerConfiguration.new_with_xml jira_call( 'getConfiguration' )
   end
+  alias_method :get_server_configuration, :server_configuration
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/users.rb

@@ -1,35 +1,83 @@
-module JIRA
-module RemoteAPI
-  # @group Working with User data
+module JIRA::RemoteAPI
+
+  # @group Users
 
   # @param [String] user_name
   # @return [JIRA::User]
-  def get_user_with_name user_name
-    JIRA::User.new_with_xml call( 'getUser', user_name ).first
+  def user_with_name user_name
+    JIRA::User.new_with_xml jira_call( 'getUser', user_name )
   end
+  alias_method :get_user_with_name, :user_with_name
 
+  ##
   # It seems that creating a user without any permission groups will trigger
   # an exception on some versions of JIRA. The irony is that this method provides
   # no way to add groups. The good news though, is that the creation will still
   # happen; but the user will have no permissions.
+  #
   # @param [String] username
   # @param [String] password
   # @param [String] full_name
   # @param [String] email
   # @return [JIRA::User,nil] depending on your JIRA version, this method may
-  #  always raise an exception instead of actually returning anything
+  #   always raise an exception instead of actually returning anything
   def create_user username, password, full_name, email
-    fragment = call( 'createUser', username, password, full_name, email ).first
+    fragment = jira_call( 'createUser', username, password, full_name, email )
     JIRA::User.new_with_xml fragment
   end
 
   # @param [String] username
   # @return [Boolean] true if successful
   def delete_user_with_name username
-    call 'deleteUser', username
+    jira_call 'deleteUser', username
+    true
+  end
+
+  # @param [String] group_name
+  # @return [JIRA::UserGroup]
+  def group_with_name group_name
+    frag = jira_call 'getGroup', group_name
+    JIRA::UserGroup.new_with_xml frag
+  end
+  alias_method :get_group_with_name, :group_with_name
+
+  # @param [JIRA::UserGroup] group
+  # @param [JIRA::User] user
+  # @return [Boolean] true if successful
+  def add_user_to_group group, user
+    jira_call 'addUserToGroup', group, user
+    true
+  end
+
+  # @param [JIRA::UserGroup] group
+  # @param [JIRA::User] user
+  # @return [Boolean]
+  def remove_user_from_group group, user
+    jira_call 'removeUserFromGroup', group, user
+    true
+  end
+
+  ##
+  # Create a new user group. You can initialize the group
+  # with a user if you wish.
+  #
+  # @param [String] group_name
+  # @param [JIRA::User] user
+  # @return [JIRA::UserGroup]
+  def create_user_group group_name, user = nil
+    frag = jira_call 'createGroup', group_name, user
+    JIRA::UserGroup.new_with_xml frag
+  end
+
+  ##
+  # @todo Find out the semantics of swap_group
+  #
+  # @param [String] group_name
+  # @param [String] swap_group
+  # @return [Boolean] true if successful
+  def delete_user_group group_name, swap_group
+    jira_call 'deleteGroup', group_name, swap_group
     true
   end
 
-  # @endgroup
-end
 end

data/lib/jiraSOAP/api/versions.rb

@@ -1,13 +1,15 @@
-module JIRA
-module RemoteAPI
-  # @group Working with Versions
+module JIRA::RemoteAPI
+
+  # @group Versions
 
   # @param [String] project_key
   # @return [Array<JIRA::Version>]
-  def get_versions_for_project project_key
-    jira_call JIRA::Version, 'getVersions', project_key
+  def versions_for_project project_key
+    array_jira_call JIRA::Version, 'getVersions', project_key
   end
+  alias_method :get_versions_for_project, :versions_for_project
 
+  ##
   # New versions cannot have the archived bit set and the release date
   # field will ignore the time of day you give it and instead insert
   # the time zone offset as the time of day.
@@ -17,34 +19,36 @@ module RemoteAPI
   #
   # Descriptions do not appear to be included with JIRA::Version objects
   # that SOAP API provides.
+  #
   # @param [String] project_key
   # @param [JIRA::Version] version
   # @return [JIRA::Version]
   def add_version_to_project_with_key project_key, version
-    JIRA::Version.new_with_xml call( 'addVersion', project_key, version ).first
+    JIRA::Version.new_with_xml jira_call( 'addVersion', project_key, version )
   end
 
+  ##
   # The archive state can only be set to true for versions that have not been
   # released. However, this is not reflected by the return value of this method.
+  #
   # @param [String] project_key
   # @param [String] version_name
   # @param [Boolean] state
   # @return [Boolean] true if successful
   def set_archive_state_for_version_for_project project_key, version_name, state
-    call 'archiveVersion', project_key, version_name, state
+    jira_call 'archiveVersion', project_key, version_name, state
     true
   end
 
+  ##
   # You can set the release state for a project with this method.
+  #
   # @param [String] project_name
   # @param [JIRA::Version] version
   # @return [Boolean] true if successful
   def release_state_for_version_for_project project_name, version
-    call 'releaseVersion', project_name, version
+    jira_call 'releaseVersion', project_name, version
     true
   end
 
-  # @endgroup
-end
 end
-

data/lib/jiraSOAP/api/worklog.rb

@@ -0,0 +1,14 @@
+module JIRA::RemoteAPI
+
+  # @group Worklogs
+
+  ##
+  # Adds a worklog to the given issue.
+  #
+  # @param [String] issue_key
+  # @param [JIRA::Worklog] worklog
+  def add_worklog_and_auto_adjust_remaining_estimate issue_key, worklog
+    JIRA::Worklog.new_with_xml call( 'addWorklogAndAutoAdjustRemainingEstimate', issue_key, worklog ).first
+  end
+
+end

data/lib/jiraSOAP/core_extensions.rb

@@ -0,0 +1,8 @@
+##
+# Monkey patches to allow the SOAP building method to not need
+# a special case for dealing with arrays.
+class Array
+  def to_soap
+    raise NotImplementedError
+  end
+end

data/lib/jiraSOAP/entities.rb

@@ -10,6 +10,7 @@ require 'jiraSOAP/entities/project_role'
 
 require 'jiraSOAP/entities/username'
 require 'jiraSOAP/entities/user'
+require 'jiraSOAP/entities/usergroup'
 
 require 'jiraSOAP/entities/field_value'
 require 'jiraSOAP/entities/custom_field_value'
@@ -38,3 +39,5 @@ require 'jiraSOAP/entities/issue'
 require 'jiraSOAP/entities/time_info'
 require 'jiraSOAP/entities/server_info'
 require 'jiraSOAP/entities/server_configuration'
+
+require 'jiraSOAP/entities/worklog'

data/lib/jiraSOAP/entities/attachment_metadata.rb

@@ -1,14 +1,33 @@
-# @todo add an attribute to fetch the attachment
+##
 # Only contains the metadata for an attachment. The URI for an attachment
 # appears to be of the form
 # "{JIRA::JIRAService.endpoint_url}/secure/attachment/{#id}/{#file_name}"
 class JIRA::AttachmentMetadata < JIRA::NamedEntity
-  add_attributes(
-    ['author',   :author,      :to_s],
-    ['filename', :file_name,   :to_s],
-    ['mimetype', :mime_type,   :to_s],
-    # Measured in bytes
-    ['filesize', :file_size,   :to_i],
-    ['created',  :create_time, :to_date]
-  )
+
+  # @return [String]
+  add_attribute :author, 'author', :content
+
+  # @return [String]
+  add_attribute :file_name, 'filename', :content
+  alias_method :filename, :file_name
+
+  # @return [String]
+  add_attribute :mime_type, 'mimetype', :content
+  alias_method :content_type, :mime_type
+
+  ##
+  # Measured in bytes
+  #
+  # @return [Number]
+  add_attribute :file_size, 'filesize', :to_i
+
+  # @return [Time]
+  add_attribute :create_time, 'created', :to_iso_date
+
+  ##
+  # Fetch the attachment from the server.
+  def attachment
+    raise NotImplementedError, 'Please implement me. :('
+  end
+
 end