jiraSOAP 0.6.1 → 0.7.1

data/lib/jiraSOAP/api/schemes.rb

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

data/lib/jiraSOAP/api/server_info.rb

@@ -0,0 +1,18 @@
+module JIRA
+module RemoteAPI
+  # @group Getting information about the server
+
+  # 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
+  end
+
+  # @return [JIRA::ServerConfiguration]
+  def get_server_configuration
+    JIRA::ServerConfiguration.new_with_xml call( 'getConfiguration' ).first
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/users.rb

@@ -0,0 +1,35 @@
+module JIRA
+module RemoteAPI
+  # @group Working with User data
+
+  # @param [String] user_name
+  # @return [JIRA::User]
+  def get_user_with_name user_name
+    JIRA::User.new_with_xml call( 'getUser', user_name ).first
+  end
+
+  # 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
+  def create_user username, password, full_name, email
+    fragment = call( 'createUser', username, password, full_name, email ).first
+    JIRA::User.new_with_xml fragment
+  end
+
+  # @param [String] username
+  # @return [Boolean] true if successful
+  def delete_user_with_name username
+    call 'deleteUser', username
+    true
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/versions.rb

@@ -0,0 +1,50 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Versions
+
+  # @param [String] project_key
+  # @return [Array<JIRA::Version>]
+  def get_versions_for_project project_key
+    jira_call JIRA::Version, 'getVersions', project_key
+  end
+
+  # 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.
+  #
+  # Remember that the @release_date field is the tentative release date,
+  # so its value is independant of the @released flag.
+  #
+  # 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
+  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
+    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
+    true
+  end
+
+  # @endgroup
+end
+end
+

data/lib/jiraSOAP/entities.rb

@@ -6,9 +6,11 @@ require 'jiraSOAP/entities/described_entity'
 require 'jiraSOAP/entities/component'
 require 'jiraSOAP/entities/field'
 require 'jiraSOAP/entities/filter'
-require 'jiraSOAP/entities/user'
 require 'jiraSOAP/entities/project_role'
 
+require 'jiraSOAP/entities/username'
+require 'jiraSOAP/entities/user'
+
 require 'jiraSOAP/entities/field_value'
 require 'jiraSOAP/entities/custom_field_value'
 
@@ -20,6 +22,8 @@ require 'jiraSOAP/entities/attachment_metadata'
 require 'jiraSOAP/entities/scheme'
 require 'jiraSOAP/entities/notification_scheme'
 require 'jiraSOAP/entities/issue_security_scheme'
+require 'jiraSOAP/entities/permission'
+require 'jiraSOAP/entities/permission_mapping'
 require 'jiraSOAP/entities/permission_scheme'
 
 require 'jiraSOAP/entities/issue_property'

data/lib/jiraSOAP/entities/attachment_metadata.rb

@@ -1,27 +1,14 @@
+# @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],
-    'filesize' => [:file_size=,   :to_i],
-    'created'  => [:create_time=, :to_date],
-  })
-
-  # @return [String]
-  attr_accessor :author
-
-  # @return [Time]
-  attr_accessor :create_time
-
-  # @return [String]
-  attr_accessor :file_name
-
-  # @return [Fixnum] measured in bytes
-  attr_accessor :file_size
-
-  # @return [String]
-  attr_accessor :mime_type
+  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]
+  )
 end

data/lib/jiraSOAP/entities/avatar.rb

@@ -1,27 +1,14 @@
 # @todo find out what the id value of @owner relates to
 # Contains a base64 encoded avatar image and metadata about the avatar.
 class JIRA::Avatar < JIRA::DynamicEntity
-  add_attributes({
-    'owner'       => [:owner=,       :to_s],
-    'type'        => [:type=,        :to_s],
-    'contentType' => [:mime_type=,   :to_s],
-    'base64Data'  => [:base64_data=, :to_s],
-    'system'      => [:system=,      :to_boolean],
-  })
-
-  # @return [String] this seems to be an id ref to some other object
-  attr_accessor :owner
-
-  # @return [String] the place where the avatar is used (e.g. 'project')
-  attr_accessor :type
-
-  # @return [String]
-  attr_accessor :mime_type
-
-  # @return [String]
-  attr_accessor :base64_data
-
-  # @return [boolean] indicates if the image is the system default
-  attr_accessor :system
-  alias_method :system?, :system
+  add_attributes(
+    # This seems to be an id ref to some other object
+    ['owner',       :owner,       :to_s],
+    # The place where the avatar is used (e.g. 'project')
+    ['type',        :type,        :to_s],
+    ['contentType', :mime_type,   :to_s],
+    ['base64Data',  :base64_data, :to_s],
+    # Indicates if the image is the system default
+    ['system',      :system,      :to_boolean]
+  )
 end

data/lib/jiraSOAP/entities/comment.rb

@@ -1,35 +1,16 @@
-# Contains a comments body and its metadata.
+# Contains a comment's body and metadata.
 class JIRA::Comment < JIRA::DynamicEntity
-  add_attributes({
-    'author'       => [:author=,            :to_s],
-    'body'         => [:body=,              :to_s],
-    'groupLevel'   => [:group_level=,       :to_s],
-    'roleLevel'    => [:role_level=,        :to_s],
-    'updateAuthor' => [:update_author=,     :to_s],
-    'created'      => [:create_time=,       :to_date],
-    'updated'      => [:last_updated_time=, :to_date]
-  })
-
-  # @return [String] a username
-  attr_accessor :author
-
-  # @return [String]
-  attr_accessor :role_level
-
-  # @return [String]
-  attr_accessor :group_level
-
-  # @return [String]
-  attr_accessor :body
-
-  # @return [Time]
-  attr_accessor :create_time
-
-  # @return [Time]
-  attr_accessor :last_updated_time
-
-  # @return [String] a username
-  attr_accessor :update_author
+  add_attributes(
+    # A username
+    ['author',       :author,            :to_s],
+    ['body',         :body,              :to_s],
+    ['groupLevel',   :group_level,       :to_s],
+    ['roleLevel',    :role_level,        :to_s],
+    # A username
+    ['updateAuthor', :update_author,     :to_s],
+    ['created',      :create_time,       :to_date],
+    ['updated',      :last_updated_time, :to_date]
+  )
 
   # @todo make this method shorter
   # @param [Handsoap::XmlMason::Node] msg

data/lib/jiraSOAP/entities/component.rb

@@ -1,5 +1,5 @@
 # Represents a component name and id only. It does not include the component
 # lead.
 class JIRA::Component < JIRA::NamedEntity
-  add_attributes({})
+  add_attributes
 end

data/lib/jiraSOAP/entities/custom_field_value.rb

@@ -7,17 +7,11 @@
 # custom fields and a field value is more flexible. You can expect the classes
 # to merge in the near future.
 class JIRA::CustomFieldValue < JIRA::DynamicEntity
-  @attributes = {
-    'customfieldId' => [:id=,     :to_s],
-    'key'           => [:key=,    :to_s],
-    'values'        => [:values=, :to_ss]
-  }
-
-  # @return [String]
-  attr_accessor :key
-
-  # @return [[String]]
-  attr_accessor :values
+  add_attributes(
+    ['customfieldId', :id,     :to_s],
+    ['key',           :key,    :to_s],
+    ['values',        :values, :to_ss]
+  )
 
   # Generate a SOAP message fragment for the object.
   # @param [Handsoap::XmlMason::Node] msg SOAP message to add the object to

data/lib/jiraSOAP/entities/described_entity.rb

@@ -1,7 +1,7 @@
 # @abstract Some named entities have a short description
 class JIRA::DescribedEntity < JIRA::NamedEntity
-  add_attributes({ 'description' => [:description=, :to_s] })
-
-  # @return [String] usually a short blurb
-  attr_accessor :description
+  add_attributes(
+    # A short blurb.
+    ['description', :description, :to_s]
+  )
 end

data/lib/jiraSOAP/entities/dynamic_entity.rb

@@ -1,8 +1,8 @@
 # @abstract Anything that can be configured has an id field.
 class JIRA::DynamicEntity < JIRA::Entity
-  add_attributes({ 'id' => [:id=, :to_s] })
-
-  # @return [String] usually a numerical value, but sometimes
-  #  prefixed with a string (e.g. '12450' or 'customfield_10000')
-  attr_accessor :id
+  add_attributes(
+    # Usually a numerical value, but sometimes prefixed with a
+    #  string (e.g. '12450' or 'customfield_10000')
+    ['id', :id, :to_s]
+  )
 end

data/lib/jiraSOAP/entities/entity.rb

@@ -1,22 +1,29 @@
 # @abstract The base class for all JIRA objects that can given by the server.
-# @todo remove the need for attr_accessor by having add_attributes make the
-#  call for me, but I will need to make a YARD plugin to fix the gap in the
-#  documentation when that happens
 class JIRA::Entity
 
   class << self
-    # @return [Hash{String => Array}] used by the metaclass
-    attr_accessor :attributes
-
-    # @param [Hash] attributes
-    # @return [Hash]
-    def add_attributes attributes
-      @attributes = ancestors[1].attributes.dup
-      @attributes.update attributes
+
+    # @return [Hash{String=>Array<Symbol,Symbol,Class*>}] used by the
+    #  metaclass for parsing XML
+    attr_accessor :parse
+
+    # @param [Array<String,Symbol,Class>] attributes
+    # @return [nil]
+    def add_attributes *attributes
+      superclass = ancestors[1]
+      @parse = superclass.parse.dup
+
+      attributes.each { |attribute|
+        attr_accessor attribute[1]
+        @parse[attribute[0]] = [:"#{attribute[1]}=", *attribute[2,2]]
+        alias_method :"#{attribute[1]}?", attribute[1] if attribute[2] == :to_boolean
+        #" ruby-mode parse fail
+      }
     end
+
   end
 
-  @attributes = {} # needs to be initialized
+  @parse = {} # needs to be initialized
 
   # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
   # @return [JIRA::Entity]
@@ -33,11 +40,19 @@ class JIRA::Entity
   #  methods into Nokogiri classes
   # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
   def initialize_with_xml frag
-    attributes = self.class.attributes
+    attributes = self.class.parse
     frag.children.each { |node|
       action = attributes[node.node_name]
       self.send action[0], (node.send *action[1..-1]) if action
       #puts "Action is #{action.inspect} for #{node.node_name}"
     }
   end
+
+  # @todo #soapify_for should become #to_soap and should take only the
+  #  optional argument for wrapper name, otherwise just makes its own
+  #  own node with appropriate subnodes and returns that as a Handsoap
+  #  document
+  def to_soap node_name = nil
+    raise NotImplementedError
+  end
 end

data/lib/jiraSOAP/entities/field.rb

@@ -1,4 +1,4 @@
 # Represents a field mapping.
 class JIRA::Field < JIRA::NamedEntity
-  add_attributes({})
+  add_attributes
 end

data/lib/jiraSOAP/entities/filter.rb

@@ -1,17 +1,8 @@
 # Represents a filter, but does not seem to include the filters JQL query.
 class JIRA::Filter < JIRA::DescribedEntity
-  add_attributes({
-    'author'  => [:author=,       :to_s],
-    'project' => [:project_name=, :to_s],
-    'xml'     => [:xml=,          :to_s]
-  })
-
-  # @return [String]
-  attr_accessor :author
-
-  # @return [String]
-  attr_accessor :project_name
-
-  # @return [nil]
-  attr_accessor :xml
+  add_attributes(
+    ['author',  :author,       :to_s],
+    ['project', :project_name, :to_s],
+    ['xml',     :xml,          :to_s]
+  )
 end

data/lib/jiraSOAP/entities/issue.rb

@@ -1,98 +1,39 @@
+# @todo add attributes for the comments and the attachment metadata
 # Contains most of the data and metadata for a JIRA issue, but does
-# not contain the {JIRA::Comment}'s or {JIRA::AttachmentMetadata}.
+# not contain the {JIRA::Comment}s or {JIRA::AttachmentMetadata}.
 #
 # This class is easily the most convoluted structure in the API, and will
 # likely be the greatest source of bugs. The irony of the situation is that
 # this structure is also the most critical to have in working order.
 #
-# @note Issues with an UNRESOLVED status will have nil for the value of
-#  #resolution.
+# @note Issues with an UNRESOLVED status will have nil for the value for
+#  {#resolution_id}.
 class JIRA::Issue < JIRA::DynamicEntity
-  add_attributes({
-    'key'               => [:key=,                 :to_s],
-    'summary'           => [:summary=,             :to_s],
-    'description'       => [:description=,         :to_s],
-    'type'              => [:type_id=,             :to_s],
-    'status'            => [:status_id=,           :to_s],
-    'assignee'          => [:assignee_username=,   :to_s],
-    'reporter'          => [:reporter_username=,   :to_s],
-    'priority'          => [:priority_id=,         :to_s],
-    'project'           => [:project_name=,        :to_s],
-    'resolution'        => [:resolution_id=,       :to_s],
-    'environment'       => [:environment=,         :to_s],
-    'votes'             => [:votes=,               :to_i],
-    'updated'           => [:last_updated_time=,   :to_date],
-    'created'           => [:create_time=,         :to_date],
-    'duedate'           => [:due_date=,            :to_date],
-    'affectsVersions'   => [:affects_versions=,    :to_objects, JIRA::Version],
-    'fixVersions'       => [:fix_versions=,        :to_objects, JIRA::Version],
-    'components'        => [:components=,          :to_objects, JIRA::Component],
-    'customFieldValues' => [:custom_field_values=, :to_objects, JIRA::CustomFieldValue],
-    'attachmentNames'   => [:attachment_names=,    :to_ss]
-  })
-
-  # @return [String]
-  attr_accessor :key
-
-  # @return [String]
-  attr_accessor :summary
-
-  # @return [String]
-  attr_accessor :description
-
-  # @return [String]
-  attr_accessor :type_id
-
-  # @return [Time]
-  attr_accessor :last_updated_time
-
-  # @return [Fixnum]
-  attr_accessor :votes
-
-  # @return [String]
-  attr_accessor :status_id
-
-  # @return [String]
-  attr_accessor :assignee_username
-
-  # @return [String]
-  attr_accessor :reporter_username
-
-  # @return [String]
-  attr_accessor :priority_id
-
-  # @return [String]
-  attr_accessor :project_name
-
-  # @return [[JIRA::Version]]
-  attr_accessor :affects_versions
-
-  # @return [Time]
-  attr_accessor :create_time
-
-  # @return [Time] this is actually a Time object with no time resolution
-  attr_accessor :due_date
-
-  # @return [[JIRA::Version]]
-  attr_accessor :fix_versions
-
-  # @return [String]
-  attr_accessor :resolution_id
-
-  # @return [String]
-  attr_accessor :environment
-
-  # @return [[JIRA::Component]]
-  attr_accessor :components
-
-  # @return [[String]]
-  attr_accessor :attachment_names
-
-  # @return [[JIRA::CustomFieldValue]]
-  attr_accessor :custom_field_values
+  add_attributes(
+    ['key',               :key,                 :to_s],
+    ['summary',           :summary,             :to_s],
+    ['description',       :description,         :to_s],
+    ['type',              :type_id,             :to_s],
+    ['status',            :status_id,           :to_s],
+    ['assignee',          :assignee_username,   :to_s],
+    ['reporter',          :reporter_username,   :to_s],
+    ['priority',          :priority_id,         :to_s],
+    ['project',           :project_name,        :to_s],
+    ['resolution',        :resolution_id,       :to_s],
+    ['environment',       :environment,         :to_s],
+    ['votes',             :votes,               :to_i],
+    ['updated',           :last_updated_time,   :to_date],
+    ['created',           :create_time,         :to_date],
+    # This is actually a Time object with no time resolution.
+    ['duedate',           :due_date,            :to_date],
+    ['affectsVersions',   :affects_versions,    :to_objects, JIRA::Version],
+    ['fixVersions',       :fix_versions,        :to_objects, JIRA::Version],
+    ['components',        :components,          :to_objects, JIRA::Component],
+    ['customFieldValues', :custom_field_values, :to_objects, JIRA::CustomFieldValue],
+    ['attachmentNames',   :attachment_names,    :to_ss]
+  )
 
   # @todo see if we can use the simple and complex array builders
-  # @todo make this method shorter
   # Generate the SOAP message fragment for an issue. Can you spot the oddities
   # and inconsistencies? (hint: there are many).
   #
@@ -109,13 +50,13 @@ class JIRA::Issue < JIRA::DynamicEntity
   # and do not contain the rest of the {JIRA::Component}/{JIRA::Version}
   # structure.
   #
-  # To get the automatic assignee we pass '-1' as the value for @assignee.
+  # To get the automatic assignee we pass `'-1'` as the value for @assignee.
   #
   # Passing an environment/due date field with a value of nil causes the
   # server to complain about the formatting of the message.
   # @param [Handsoap::XmlMason::Node] msg  message the node to add the object to
   def soapify_for(msg)
-    #might be going away, since it appears to have no effect at creation time
+    # might be going away, since it appears to have no effect at creation time
     msg.add 'reporter', @reporter_name unless @reporter.nil?
 
     msg.add 'priority', @priority_id