jiraSOAP 0.7.1 → 0.8.0

data/lib/jiraSOAP/entities/avatar.rb

@@ -1,14 +1,33 @@
+##
 # @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(
-    # 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]
-  )
+
+  ##
+  # This seems to be an id ref to some other object
+  #
+  # @return [String]
+  add_attribute :owner, 'owner', :content
+
+  ##
+  # The place where the avatar is used (e.g. 'project')
+  #
+  # @return [String]
+  add_attribute :type, 'type', :content
+
+  # @return [String]
+  add_attribute :mime_type, 'contentType', :content
+  alias_method :content_type, :mime_type
+
+  # @return [String]
+  add_attribute :base64_data, 'base64Data', :content
+  alias_method :data, :base64_data
+
+  ##
+  # Indicates if the image is the system default
+  #
+  # @return [Boolean]
+  add_attribute :system, 'system', :to_boolean
+
 end

data/lib/jiraSOAP/entities/comment.rb

@@ -1,18 +1,43 @@
+##
 # Contains a comment's body and metadata.
 class JIRA::Comment < JIRA::DynamicEntity
-  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]
-  )
 
+  ##
+  # A username
+  #
+  # @return [String]
+  add_attribute :author, 'author', :content
+
+  # @return [String]
+  add_attribute :body, 'body', :content
+
+  # @return [String]
+  add_attribute :group_level, 'groupLevel', :content
+
+  # @return [String]
+  add_attribute :role_level, 'roleLevel', :content
+
+  ##
+  # A username
+  #
+  # @return [String]
+  add_attribute :update_author, 'updateAuthor', :content
+
+  # @return [Time]
+  add_attribute :create_time, 'created', :to_iso_date
+
+  # @return [Time]
+  add_attribute :last_updated_time, 'updated', :to_iso_date
+
+  ##
+  # Add a created comment to an issue
+  def add_to issue_key
+    raise NotImplementedError, 'Please implement me. :('
+  end
+
+  ##
   # @todo make this method shorter
+  #
   # @param [Handsoap::XmlMason::Node] msg
   # @return [Handsoap::XmlMason::Node]
   def soapify_for(msg)
@@ -23,4 +48,5 @@ class JIRA::Comment < JIRA::DynamicEntity
     msg.add 'roleLevel', @role_level
     msg.add 'updateAuthor', @update_author
   end
+
 end

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
 end

data/lib/jiraSOAP/entities/custom_field_value.rb

@@ -1,19 +1,23 @@
-# @todo see if @key is always nil from the server, maybe we can remove it
-# Represents an instance of a custom field (with values). This object is used
-# as a member of {JIRA::Issue} objects.
+##
+# @note There are no API methods that directly create objects of this class,
+#       they are only created as an attribute of {JIRA::Issue} objects.
+# @todo See if @key is always nil from the server, maybe we can remove it
 #
-# 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.
+# Represents an instance of a custom field (with values).
 class JIRA::CustomFieldValue < JIRA::DynamicEntity
-  add_attributes(
-    ['customfieldId', :id,     :to_s],
-    ['key',           :key,    :to_s],
-    ['values',        :values, :to_ss]
-  )
 
+  # @return [String]
+  add_attribute :id, 'customfieldId', :content
+
+  # @return [String]
+  add_attribute :key, 'key', :content
+
+  # @return [Array<String>]
+  add_attribute :values, 'values', :contents_of_children
+
+  ##
   # 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]
@@ -24,4 +28,5 @@ class JIRA::CustomFieldValue < JIRA::DynamicEntity
       submsg.add_simple_array 'values', @values
     end
   end
+
 end

data/lib/jiraSOAP/entities/described_entity.rb

@@ -1,7 +1,11 @@
-# @abstract Some named entities have a short description
+##
+# @abstract A named entity that also has a short description
 class JIRA::DescribedEntity < JIRA::NamedEntity
-  add_attributes(
-    # A short blurb.
-    ['description', :description, :to_s]
-  )
+
+  ##
+  # A short blurb
+  #
+  # @return [String]
+  add_attribute :description, 'description', :content
+
 end

data/lib/jiraSOAP/entities/dynamic_entity.rb

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

data/lib/jiraSOAP/entities/entity.rb

@@ -1,24 +1,42 @@
+##
 # @abstract The base class for all JIRA objects that can given by the server.
 class JIRA::Entity
 
   class << self
 
-    # @return [Hash{String=>Array<Symbol,Symbol,Class*>}] used by the
-    #  metaclass for parsing XML
+    # @return [Hash{String=>Array(Symbol,Symbol,Class*)}] used for parsing XML
     attr_accessor :parse
 
-    # @param [Array<String,Symbol,Class>] attributes
+    ##
+    # Define the callback to automatically initialize the build and parse
+    # tables when any subclass is defined.
+    def inherited subclass
+      subclass.parse = @parse.dup
+    end
+
+    ##
+    # @todo Add a way to signify if an attribute should not be used in
+    #       message building, as some attributes should never be included
+    #       in a SOAP message.
+    #
+    # Define a single instance attribute on the class including the
+    # specification on how to parse the XML output and how to build
+    # SOAP messages.
+    #
+    # Predicate methods will automatically be created if the transformer
+    # method is `:to_boolean`.
+    #
+    # @param [Symbol] name name of the attribute to create
+    # @param [String] jira_name name of the XML tag to look for when
+    #   parsing responses from the server
+    # @param [Symbol,Array(Symbol,Class)] transformer either the method
+    #   name to transform some XML contents, or the method name and the
+    #   class to build from the attribute
     # @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
-      }
+    def add_attribute name, jira_name, transformer
+      attr_accessor name
+      alias_method "#{name}?", name if transformer == :to_boolean
+      @parse[jira_name] = [:"#{name}=", *transformer]
     end
 
   end
@@ -33,26 +51,14 @@ class JIRA::Entity
     entity
   end
 
-  # @todo put debug message through the logger
-  # @todo make this faster by cutting out NokogiriDriver,
-  #  but I will need to add an accessor for @element of the
-  #  driver object and then need to inject the marshaling
-  #  methods into Nokogiri classes
-  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  # @param [Nokogiri::XML::Element] element
   def initialize_with_xml frag
     attributes = self.class.parse
     frag.children.each { |node|
-      action = attributes[node.node_name]
+      action = attributes[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
 end

data/lib/jiraSOAP/entities/field_value.rb

@@ -1,18 +1,27 @@
-# A structure that is a bit of a hack; it is just a key-value pair that
-# is used by {RemoteAPI#update_issue}.
+##
+# This class is a bit of a hack; it is really just a key-value pair and only
+# used with {RemoteAPI#update_issue}.
 class JIRA::FieldValue
 
-  # @return [String] the name for regular fields, and the id for custom fields
+  ##
+  # The name for regular fields, and the id for custom fields
+  #
+  # @return [String]
   attr_accessor :field_name
 
-  # @return [Array(#to_s)] an array for the values, usually a single
+  ##
+  # An array for the values, usually only has one object
+  #
+  # @return [Array<#to_s>]
   attr_accessor :values
 
   # @param [String] field_name
   # @param [Array] values
-  def initialize(field_name = nil, values = nil)
+  def initialize field_name = nil, values = nil
     @field_name = field_name
-    @values     = values
+    if values
+      @values = values.is_a?( ::Array ) ? values : [values]
+    end
   end
 
   # @todo soapify properly for custom objects (JIRA module).
@@ -25,4 +34,5 @@ class JIRA::FieldValue
       message.add_simple_array 'values', @values unless @values.nil?
     end
   end
+
 end

data/lib/jiraSOAP/entities/filter.rb

@@ -1,8 +1,21 @@
+##
+# @note You can only read filters from the server, there are no API methods
+#       for creating, updating, or deleting filters from the server.
+#
 # 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]
+  add_attribute :author, 'author', :content
+
+  # @return [String]
+  add_attribute :project_name, 'project', :content
+
+  ##
+  # @todo Find out what this is for, perhaps it is the XML form of
+  #       equivalent JQL query?
+  #
+  # @return [String]
+  add_attribute :xml, 'xml', :content
+
 end

data/lib/jiraSOAP/entities/issue.rb

@@ -1,39 +1,82 @@
-# @todo add attributes for the comments and the attachment metadata
+##
+# @note Issues with an UNRESOLVED status will have nil for the value for
+#       {#resolution_id}.
+# @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}.
 #
 # 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 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],
-    # 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]
-  )
 
+  # @return [String]
+  add_attribute :key, 'key', :content
+
+  # @return [String]
+  add_attribute :summary, 'summary', :content
+
+  # @return [String]
+  add_attribute :description, 'description', :content
+
+  # @return [String]
+  add_attribute :type_id, 'type', :content
+
+  # @return [String]
+  add_attribute :status_id, 'status', :content
+
+  # @return [String]
+  add_attribute :assignee_username, 'assignee', :content
+
+  # @return [String]
+  add_attribute :reporter_username, 'reporter', :content
+
+  # @return [String]
+  add_attribute :priority_id, 'priority', :content
+
+  # @return [String]
+  add_attribute :project_name, 'project', :content
+
+  # @return [String]
+  add_attribute :resolution_id, 'resolution', :content
+
+  # @return [String]
+  add_attribute :environment, 'environment', :content
+
+  # @return [Number]
+  add_attribute :votes, 'votes', :to_i
+
+  # @return [Time]
+  add_attribute :last_updated_time, 'updated', :to_iso_date
+
+  # @return [Time]
+  add_attribute :create_time, 'created', :to_iso_date
+
+  ##
+  # This is actually a Time object with no time resolution.
+  #
+  # @return [Time]
+  add_attribute :due_date, 'duedate', :to_iso_date
+
+  # @return [Array<JIRA::Version>]
+  add_attribute :affects_versions, 'affectsVersions', [:children_as_objects, JIRA::Version]
+
+  # @return [Array<JIRA::Version>]
+  add_attribute :fix_versions, 'fixVersions', [:children_as_objects, JIRA::Version]
+
+  # @return [Array<JIRA::Component>]
+  add_attribute :components, 'components', [:children_as_objects, JIRA::Component]
+
+  # @return [Array<JIRA::CustomFieldValue>]
+  add_attribute :custom_field_values, 'customFieldValues', [:children_as_objects, JIRA::CustomFieldValue]
+
+  # @return [Array<String>]
+  add_attribute :attachment_names, 'attachmentNames', :contents_of_children
+
+  ##
   # @todo see if we can use the simple and complex array builders
+  #
   # Generate the SOAP message fragment for an issue. Can you spot the oddities
   # and inconsistencies? (hint: there are many).
   #
@@ -54,8 +97,9 @@ class JIRA::Issue < JIRA::DynamicEntity
   #
   # 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)
+  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?
 
@@ -87,10 +131,11 @@ class JIRA::Issue < JIRA::DynamicEntity
       }
     end
 
-    msg.add 'assignee', (@assignee_name || '-1')
+    msg.add 'assignee', (@assignee_username || '-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