jiraSOAP 0.4.0 → 0.5.0

data/lib/jiraSOAP/entities.rb

@@ -0,0 +1,26 @@
+require 'jiraSOAP/entities/abstract'
+require 'jiraSOAP/entities/read_only'
+require 'jiraSOAP/entities/field_value'
+require 'jiraSOAP/entities/user'
+
+require 'jiraSOAP/entities/avatar'
+require 'jiraSOAP/entities/comment'
+require 'jiraSOAP/entities/issue'
+
+require 'jiraSOAP/entities/filter'
+require 'jiraSOAP/entities/version'
+require 'jiraSOAP/entities/attachments'
+require 'jiraSOAP/entities/project'
+require 'jiraSOAP/entities/schemes'
+require 'jiraSOAP/entities/issue_properties'
+
+module JIRA
+  # Represents a field mapping.
+  class Field < JIRA::NamedEntity
+  end
+
+  # Represents a component description for a project. It does not include
+  # the component lead.
+  class Component < JIRA::NamedEntity
+  end
+end

data/lib/jiraSOAP/entities/abstract.rb

@@ -0,0 +1,95 @@
+module JIRA
+
+# @abstract
+# The base class for all JIRA objects that can be created by the server.
+class Entity
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  # @return [JIRA::Entity]
+  def self.new_with_xml_fragment(frag)
+    entity = allocate
+    entity.initialize_with_xml_fragment frag
+    entity
+  end
+
+  # @raise [NotImplementedError] this method MUST be implemented in a non
+  #  abstract descendant
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    raise NotImplementedError.new, 'Subclasses should override and implement'
+  end
+end
+
+# @abstract
+# Most JIRA objects will have an id attribute as a unique identifier in
+# their area.
+class DynamicEntity < JIRA::Entity
+
+  # @return [String] usually holds a numerical value but for consistency with
+  #  with id's from custom fields this attribute is always a String
+  attr_accessor :id
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    @id = (frag/'id').to_s
+  end
+end
+
+# @abstract
+# Many JIRA objects include a name.
+class NamedEntity < JIRA::DynamicEntity
+
+  # @return [String] a plain language name
+  attr_accessor :name
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @name = (frag/'name').to_s
+  end
+end
+
+# @abstract
+# Several JIRA objects include a short description.
+class DescribedEntity < JIRA::NamedEntity
+
+  # @return [String] usually a short blurb
+  attr_accessor :description
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @description = (frag/'description').to_s
+  end
+end
+
+# @abstract
+# Represents a scheme used by the server. Not very useful for the sake of the
+# API; a more useful case might be if you wanted to emulate the server's
+# behaviour.
+class Scheme < JIRA::DescribedEntity
+  # Schemes that inherit this class will have to be careful when they try
+  # to encode the scheme type in an xml message.
+  # @return [String]
+  def type
+    self.class.to_s
+  end
+end
+
+# @abstract
+# A common base for most issue properties. Core issue properties have
+# an icon to go with them to help identify properties of issues more
+# quickly.
+class IssueProperty < JIRA::DescribedEntity
+
+  # @return [URL] A NSURL on MacRuby and a URI::HTTP object in CRuby
+  attr_accessor :icon
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @icon = (frag/'icon').to_url
+  end
+end
+
+end

data/lib/jiraSOAP/entities/attachments.rb

@@ -0,0 +1,35 @@
+module JIRA
+
+# 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}/{#filename}"
+class AttachmentMetadata < JIRA::NamedEntity
+
+  # @return [String]
+  attr_accessor :author
+
+  # @return [Time]
+  attr_accessor :create_date
+
+  # @return [String]
+  attr_accessor :filename
+
+  # @return [Fixnum] measured in bytes
+  attr_accessor :file_size
+
+  # @return [String]
+  attr_accessor :mime_type
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @author, @filename, @mime_type, @file_size, @create_date =
+      frag.nodes( ['author',   :to_s],
+                  ['filename', :to_s],
+                  ['mimetype', :to_s],
+                  ['filesize', :to_i],
+                  ['created',  :to_date] )
+  end
+end
+
+end

data/lib/jiraSOAP/entities/avatar.rb

@@ -0,0 +1,36 @@
+module JIRA
+
+# Contains a base64 encoded avatar image and metadata about the avatar.
+class Avatar < JIRA::DynamicEntity
+
+  # @return [String]
+  attr_accessor :owner
+
+  # @return [String] the place where the avatar is used
+  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
+
+  # @return [boolean] true if avatar is the default system avatar, else false
+  def system?; @system; end
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @owner, @type, @mime_type, @base64_data, @system =
+      frag.nodes( ['owner',       :to_s],
+                  ['type',        :to_s],
+                  ['contentType', :to_s],
+                  ['base64Data',  :to_s],
+                  ['system',      :to_boolean] )
+  end
+end
+
+end

data/lib/jiraSOAP/entities/comment.rb

@@ -0,0 +1,54 @@
+module JIRA
+
+# Contains a comments body and its metadata.
+class Comment < JIRA::DynamicEntity
+
+  # @return [String]
+  attr_accessor :original_author
+
+  # @return [String]
+  attr_accessor :role_level
+
+  # @return [String]
+  attr_accessor :group_level
+
+  # @return [String]
+  attr_accessor :body
+
+  # @return [Time]
+  attr_accessor :create_date
+
+  # @return [Time]
+  attr_accessor :last_updated
+
+  # @return [String]
+  attr_accessor :update_author
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @original_author, @body, @group_level, @role_level,
+    @update_author, @create_date, @last_updated =
+      frag.nodes( ['author',       :to_s],
+                  ['body',         :to_s],
+                  ['groupLevel',   :to_s],
+                  ['roleLevel',    :to_s],
+                  ['updateAuthor', :to_s],
+                  ['created',      :to_date],
+                  ['updated',      :to_date] )
+  end
+
+  # @todo make this method shorter
+  # @param [Handsoap::XmlMason::Node] msg
+  # @return [Handsoap::XmlMason::Node]
+  def soapify_for(msg)
+    msg.add 'id', @id
+    msg.add 'author', @original_author
+    msg.add 'body', @body
+    msg.add 'groupLevel', @group_level
+    msg.add 'roleLevel', @role_level
+    msg.add 'updateAuthor', @update_author
+  end
+end
+
+end

data/lib/jiraSOAP/entities/field_value.rb

@@ -0,0 +1,73 @@
+module JIRA
+
+# A structure that is a bit of a hack. It is essentially just a key-value pair
+# that is used by {RemoteAPI#update_issue}.
+class FieldValue
+
+  # @return [String] the name for regular fields, and the id for custom fields
+  attr_accessor :field_name
+
+  # @return [[String,Time,URL,nil]] Whatever the type, just make sure it is
+  #   wrapped in an array.
+  attr_accessor :values
+
+  # @param [String] field_name
+  # @param [Array] values
+  def initialize(field_name = nil, values = nil)
+    @field_name = field_name
+    @values     = values
+  end
+
+  # @todo soapify properly for custom objects (JIRA module).
+  # @param [Handsoap::XmlMason::Node] message the node to add the object to
+  # @param [String] label name for the tags that wrap the message
+  # @return [Handsoap::XmlMason::Element]
+  def soapify_for(message, label = 'fieldValue')
+    message.add label do |message|
+      message.add 'id', @field_name
+      message.add_simple_array 'values', @values unless @values.nil?
+    end
+  end
+end
+
+
+# Represents an instance of a custom field (with values). This object is used
+# as a member of {JIRA::Issue} objects.
+#
+# The structure of this class resembles JIRA::FieldValue, it is different
+# in that @values will always be stored as an Array of String objects for
+# custom fields and a field value is more flexible. You can expect the classes
+# to merge in the near future.
+# @todo see if @key is always nil from the server, maybe we can remove it
+# @todo merge this class with JIRA::FieldValue
+class CustomFieldValue < JIRA::DynamicEntity
+
+  # @return [String]
+  attr_accessor :key
+
+  # @return [[String]]
+  attr_accessor :values
+
+  # @note careful, value of id is actually customfieldId
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    @id, @key, @values =
+      frag.nodes( ['customfieldId', :to_s],
+                  ['key', :to_s],
+                  ['values/*', :to_ss] )
+  end
+
+  # Generate a SOAP message fragment for the object.
+  # @param [Handsoap::XmlMason::Node] msg SOAP message to add the object to
+  # @param [String] label tag name used in wrapping tags
+  # @return [Handsoap::XmlMason::Element]
+  def soapify_for(msg, label = 'customFieldValues')
+    msg.add label do |submsg|
+      submsg.add 'customfieldId', @id
+      submsg.add 'key', @key
+      submsg.add_simple_array 'values', @values
+    end
+  end
+end
+
+end

data/lib/jiraSOAP/entities/filter.rb

@@ -0,0 +1,26 @@
+module JIRA
+
+# Represents a filter, but does not seem to include the filters JQL query.
+# @todo find out what @project is supposed to be for
+class Filter < JIRA::DescribedEntity
+
+  # @return [String]
+  attr_accessor :author
+
+  # @return [String]
+  attr_accessor :project
+
+  # @return [nil]
+  attr_accessor :xml
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @author, @project, @xml =
+      frag.nodes( ['author',  :to_s],
+                  ['project', :to_s],
+                  ['xml',     :to_s] )
+  end
+end
+
+end

data/lib/jiraSOAP/entities/issue.rb

@@ -0,0 +1,166 @@
+module JIRA
+
+# Contains most of the data and metadata for a JIRA issue, but does
+# 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.
+#
+# Issues with an UNRESOLVED status will have nil for the value of @resolution.
+class Issue < JIRA::DynamicEntity
+
+  # @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
+
+  # @return [Fixnum]
+  attr_accessor :votes
+
+  # @return [String]
+  attr_accessor :status_id
+
+  # @return [String]
+  attr_accessor :assignee_name
+
+  # @return [String]
+  attr_accessor :reporter_name
+
+  # @return [String]
+  attr_accessor :priority_id
+
+  # @return [String]
+  attr_accessor :project_name
+
+  # @return [[JIRA::Version]]
+  attr_accessor :affects_versions
+
+  # @return [Time]
+  attr_accessor :create_date
+
+  # @return [Time]
+  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
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  def initialize_with_xml_fragment(frag)
+    super frag
+    @key, @summary, @description, @type_id, @status_id,
+    @assignee_name, @reporter_name, @priority_id, @project_name,
+    @resolution_id, @environment, @votes, @last_updated, @create_date,
+    @due_date, @affects_versions, @fix_versions, @components,
+    @custom_field_values, @attachment_names =
+      frag.nodes( ['key',                 :to_s],
+                  ['summary',             :to_s],
+                  ['description',         :to_s],
+                  ['type',                :to_s],
+                  ['status',              :to_s],
+                  ['assignee',            :to_s],
+                  ['reporter',            :to_s],
+                  ['priority',            :to_s],
+                  ['project',             :to_s],
+                  ['resolution',          :to_s],
+                  ['environment',         :to_s],
+                  ['votes',               :to_i],
+                  ['updated',             :to_date],
+                  ['created',             :to_date],
+                  ['duedate',             :to_date],
+                  ['affectsVersions/*',   :to_objects, JIRA::Version],
+                  ['fixVersions/*',       :to_objects, JIRA::Version],
+                  ['components/*',        :to_objects, JIRA::Component],
+                  ['customFieldValues/*', :to_objects, JIRA::CustomFieldValue],
+                  ['attachmentNames/*',   :to_ss] )
+  end
+
+  # Generate the SOAP message fragment for an issue. Can you spot the oddities
+  # and inconsistencies? (hint: there are many).
+  #
+  # We don't bother including fields that are ignored. I tried to only
+  # ignore fields that will never be needed at creation time, but I may have
+  # messed up.
+  #
+  # We don't wrap the whole thing in 'issue' tags for
+  # {#RemoteAPI#create_issue_with_issue} calls; this is an inconsistency in the
+  # way jiraSOAP works and may need to be worked around for other {RemoteAPI}
+  # methods.
+  #
+  # Servers only seem to accept issues if components/versions are just ids
+  # 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.
+  #
+  # Passing an environment/due date field with a value of nil causes the
+  # server to complain about the formatting of the message.
+  # @todo see if we can use the simple and complex array builders
+  # @todo make this method shorter
+  # @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
+    msg.add 'reporter', @reporter_name unless @reporter.nil?
+
+    msg.add 'priority', @priority_id
+    msg.add 'type', @type_id
+    msg.add 'project', @project_name
+
+    msg.add 'summary', @summary
+    msg.add 'description', @description
+
+    msg.add 'components' do |submsg|
+      (@components || []).each { |component|
+        submsg.add 'components' do |component_msg|
+          component_msg.add 'id', component.id
+        end
+      }
+    end
+    msg.add 'affectsVersions' do |submsg|
+      (@affects_versions || []).each { |version|
+        submsg.add 'affectsVersions' do |version_msg|
+          version_msg.add 'id', version.id
+        end
+      }
+    end
+    msg.add 'fixVersions' do |submsg|
+      (@fix_versions || []).each { |version|
+        submsg.add 'fixVersions' do |version_msg|
+          version_msg.add 'id', version.id end
+      }
+    end
+
+    msg.add 'assignee', (@assignee_name || '-1')
+    msg.add_complex_array 'customFieldValues', (@custom_field_values || [])
+
+    msg.add 'environment', @environment unless @environment.nil?
+    msg.add 'duedate', @due_date.xmlschema unless @due_date.nil?
+  end
+end
+
+end