jiraSOAP 0.5.3 → 0.6.0

data/lib/jiraSOAP/entities.rb

@@ -1,26 +1,36 @@
-require 'jiraSOAP/entities/abstract'
-require 'jiraSOAP/entities/read_only'
-require 'jiraSOAP/entities/field_value'
+require 'jiraSOAP/entities/entity'
+require 'jiraSOAP/entities/dynamic_entity'
+require 'jiraSOAP/entities/named_entity'
+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/field_value'
+require 'jiraSOAP/entities/custom_field_value'
 
 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'
+require 'jiraSOAP/entities/attachment_metadata'
+
+require 'jiraSOAP/entities/scheme'
+require 'jiraSOAP/entities/notification_scheme'
+require 'jiraSOAP/entities/issue_security_scheme'
+require 'jiraSOAP/entities/permission_scheme'
 
-module JIRA
-  # Represents a field mapping.
-  class Field < JIRA::NamedEntity
-  end
+require 'jiraSOAP/entities/issue_property'
+require 'jiraSOAP/entities/resolution'
+require 'jiraSOAP/entities/status'
+require 'jiraSOAP/entities/priority'
+require 'jiraSOAP/entities/issue_type'
+
+require 'jiraSOAP/entities/project'
+require 'jiraSOAP/entities/issue'
 
-  # Represents a component description for a project. It does not include
-  # the component lead.
-  class Component < JIRA::NamedEntity
-  end
-end
+require 'jiraSOAP/entities/time_info'
+require 'jiraSOAP/entities/server_info'
+require 'jiraSOAP/entities/server_configuration'

data/lib/jiraSOAP/entities/attachment_metadata.rb

@@ -0,0 +1,27 @@
+# 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
+end

data/lib/jiraSOAP/entities/avatar.rb

@@ -1,12 +1,18 @@
-module JIRA
-
+# @todo find out what the id value of @owner relates to
 # Contains a base64 encoded avatar image and metadata about the avatar.
-class Avatar < JIRA::DynamicEntity
-
-  # @return [String]
+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
+  # @return [String] the place where the avatar is used (e.g. 'project')
   attr_accessor :type
 
   # @return [String]
@@ -18,17 +24,4 @@ class Avatar < JIRA::DynamicEntity
   # @return [boolean] indicates if the image is the system default
   attr_accessor :system
   alias_method :system?, :system
-
-  # @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

@@ -1,10 +1,17 @@
-module JIRA
-
 # Contains a comments body and its metadata.
-class Comment < JIRA::DynamicEntity
-
-  # @return [String]
-  attr_accessor :original_author
+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
@@ -16,39 +23,23 @@ class Comment < JIRA::DynamicEntity
   attr_accessor :body
 
   # @return [Time]
-  attr_accessor :create_date
+  attr_accessor :create_time
 
   # @return [Time]
-  attr_accessor :last_updated
+  attr_accessor :last_updated_time
 
-  # @return [String]
+  # @return [String] a username
   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 'author', @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/component.rb

@@ -0,0 +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

@@ -0,0 +1,33 @@
+# @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.
+#
+# 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.
+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
+
+  # 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

data/lib/jiraSOAP/entities/described_entity.rb

@@ -0,0 +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
+end

data/lib/jiraSOAP/entities/dynamic_entity.rb

@@ -0,0 +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
+end

data/lib/jiraSOAP/entities/entity.rb

@@ -0,0 +1,43 @@
+# @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
+    end
+  end
+
+  @attributes = {} # needs to be initialized
+
+  # @param [Handsoap::XmlQueryFront::NokogiriDriver] frag
+  # @return [JIRA::Entity]
+  def self.new_with_xml frag
+    entity = allocate
+    entity.initialize_with_xml frag
+    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
+  def initialize_with_xml frag
+    attributes = self.class.attributes
+    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
+end

data/lib/jiraSOAP/entities/field.rb

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

data/lib/jiraSOAP/entities/field_value.rb

@@ -1,14 +1,11 @@
-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
+# A structure that is a bit of a hack; it is just a key-value pair that
+# is used by {RemoteAPI#update_issue}.
+class JIRA::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.
+  # @return [Array(#to_s)] an array for the values, usually a single
   attr_accessor :values
 
   # @param [String] field_name
@@ -29,45 +26,3 @@ class FieldValue
     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

@@ -1,26 +1,17 @@
-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
+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
+  attr_accessor :project_name
 
   # @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

@@ -1,5 +1,3 @@
-module JIRA
-
 # Contains most of the data and metadata for a JIRA issue, but does
 # not contain the {JIRA::Comment}'s or {JIRA::AttachmentMetadata}.
 #
@@ -7,8 +5,31 @@ module JIRA
 # 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
+# @note Issues with an UNRESOLVED status will have nil for the value of
+#  #resolution.
+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
@@ -23,7 +44,7 @@ class Issue < JIRA::DynamicEntity
   attr_accessor :type_id
 
   # @return [Time]
-  attr_accessor :last_updated
+  attr_accessor :last_updated_time
 
   # @return [Fixnum]
   attr_accessor :votes
@@ -32,10 +53,10 @@ class Issue < JIRA::DynamicEntity
   attr_accessor :status_id
 
   # @return [String]
-  attr_accessor :assignee_name
+  attr_accessor :assignee_username
 
   # @return [String]
-  attr_accessor :reporter_name
+  attr_accessor :reporter_username
 
   # @return [String]
   attr_accessor :priority_id
@@ -47,9 +68,9 @@ class Issue < JIRA::DynamicEntity
   attr_accessor :affects_versions
 
   # @return [Time]
-  attr_accessor :create_date
+  attr_accessor :create_time
 
-  # @return [Time]
+  # @return [Time] this is actually a Time object with no time resolution
   attr_accessor :due_date
 
   # @return [[JIRA::Version]]
@@ -70,36 +91,8 @@ class Issue < JIRA::DynamicEntity
   # @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
-
+  # @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).
   #
@@ -120,8 +113,6 @@ class 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.
-  # @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
@@ -162,5 +153,3 @@ class Issue < JIRA::DynamicEntity
     msg.add 'duedate', @due_date.xmlschema unless @due_date.nil?
   end
 end
-
-end