lib/jira/base.rb
require 'active_support/core_ext/string'
require 'active_support/inflector'
require 'set'
module JIRA
# This class provides the basic object <-> REST mapping for all JIRA::Resource subclasses,
# i.e. the Create, Retrieve, Update, Delete lifecycle methods.
#
# == Lifecycle methods
#
# Note that not all lifecycle
# methods are available for all resources, for example some resources cannot be updated
# or deleted.
#
# === Retrieving all resources
#
# client.Resource.all
#
# === Retrieving a single resource
#
# client.Resource.find(id)
#
# === Creating a resource
#
# resource = client.Resource.build({'name' => '')
# resource.save
#
# === Updating a resource
#
# resource = client.Resource.find(id)
# resource.save('updated_attribute' => 'new value')
#
# === Deleting a resource
#
# resource = client.Resource.find(id)
# resource.delete
#
# == Nested resources
#
# Some resources are not defined in the top level of the URL namespace
# within the JIRA API, but are always nested under the context of another
# resource. For example, a JIRA::Resource::Comment always belongs to a
# JIRA::Resource::Issue.
#
# These resources must be indexed and built from an instance of the class
# they are nested under:
#
# issue = client.Issue.find(id)
# comments = issue.comments
# new_comment = issue.comments.build
#
class Base
QUERY_PARAMS_FOR_SINGLE_FETCH = Set.new %i[expand fields]
QUERY_PARAMS_FOR_SEARCH = Set.new %i[expand fields startAt maxResults]
# A reference to the JIRA::Client used to initialize this resource.
attr_reader :client
# Returns true if this instance has been fetched from the server
attr_accessor :expanded
# Returns true if this instance has been deleted from the server
attr_accessor :deleted
# The hash of attributes belonging to this instance. An exact
# representation of the JSON returned from the JIRA API
attr_accessor :attrs
alias expanded? expanded
alias deleted? deleted
def initialize(client, options = {})
@client = client
@attrs = options[:attrs] || {}
@expanded = options[:expanded] || false
@deleted = false
# If this class has any belongs_to relationships, a value for
# each of them must be passed in to the initializer.
self.class.belongs_to_relationships.each do |relation|
if options[relation]
instance_variable_set("@#{relation}", options[relation])
instance_variable_set("@#{relation}_id", options[relation].key_value)
elsif options["#{relation}_id".to_sym]
instance_variable_set("@#{relation}_id", options["#{relation}_id".to_sym])
else
raise ArgumentError, "Required option #{relation.inspect} missing" unless options[relation]
end
end
end
# The class methods are never called directly, they are always
# invoked from a BaseFactory subclass instance.
def self.all(client, options = {})
response = client.get(collection_path(client))
json = parse_json(response.body)
json = json[endpoint_name.pluralize] if collection_attributes_are_nested
json.map do |attrs|
new(client, { attrs: attrs }.merge(options))
end
end
# Finds and retrieves a resource with the given ID.
def self.find(client, key, options = {})
instance = new(client, options)
instance.attrs[key_attribute.to_s] = key
instance.fetch(false, query_params_for_single_fetch(options))
instance
end
# Builds a new instance of the resource with the given attributes.
# These attributes will be posted to the JIRA Api if save is called.
def self.build(client, attrs)
new(client, attrs: attrs)
end
# Returns the name of this resource for use in URL components.
# E.g.
# JIRA::Resource::Issue.endpoint_name
# # => issue
def self.endpoint_name
name.split('::').last.downcase
end
# Returns the full path for a collection of this resource.
# E.g.
# JIRA::Resource::Issue.collection_path
# # => /jira/rest/api/2/issue
def self.collection_path(client, prefix = '/')
client.options[:rest_base_path] + prefix + endpoint_name
end
# Returns the singular path for the resource with the given key.
# E.g.
# JIRA::Resource::Issue.singular_path('123')
# # => /jira/rest/api/2/issue/123
#
# If a prefix parameter is provided it will be injected between the base
# path and the endpoint.
# E.g.
# JIRA::Resource::Comment.singular_path('456','/issue/123/')
# # => /jira/rest/api/2/issue/123/comment/456
def self.singular_path(client, key, prefix = '/')
collection_path(client, prefix) + '/' + key
end
# Returns the attribute name of the attribute used for find.
# Defaults to :id unless overridden.
def self.key_attribute
:id
end
def self.parse_json(string) # :nodoc:
JSON.parse(string)
end
# Declares that this class contains a singular instance of another resource
# within the JSON returned from the JIRA API.
#
# class Example < JIRA::Base
# has_one :child
# end
#
# example = client.Example.find(1)
# example.child # Returns a JIRA::Resource::Child
#
# The following options can be used to override the default behaviour of the
# relationship:
#
# [:attribute_key] The relationship will by default reference a JSON key on the
# object with the same name as the relationship.
#
# has_one :child # => {"id":"123",{"child":{"id":"456"}}}
#
# Use this option if the key in the JSON is named differently.
#
# # Respond to resource.child, but return the value of resource.attrs['kid']
# has_one :child, :attribute_key => 'kid' # => {"id":"123",{"kid":{"id":"456"}}}
#
# [:class] The class of the child instance will be inferred from the name of the
# relationship. E.g. <tt>has_one :child</tt> will return a <tt>JIRA::Resource::Child</tt>.
# Use this option to override the inferred class.
#
# has_one :child, :class => JIRA::Resource::Kid
# [:nested_under] In some cases, the JSON return from JIRA is nested deeply for particular
# relationships. This option allows the nesting to be specified.
#
# # Specify a single depth of nesting.
# has_one :child, :nested_under => 'foo'
# # => Looks for {"foo":{"child":{}}}
# # Specify deeply nested JSON
# has_one :child, :nested_under => ['foo', 'bar', 'baz']
# # => Looks for {"foo":{"bar":{"baz":{"child":{}}}}}
def self.has_one(resource, options = {})
attribute_key = options[:attribute_key] || resource.to_s
child_class = options[:class] || ('JIRA::Resource::' + resource.to_s.classify).constantize
define_method(resource) do
attribute = maybe_nested_attribute(attribute_key, options[:nested_under])
return nil unless attribute
child_class.new(client, attrs: attribute)
end
end
# Declares that this class contains a collection of another resource
# within the JSON returned from the JIRA API.
#
# class Example < JIRA::Base
# has_many :children
# end
#
# example = client.Example.find(1)
# example.children # Returns an instance of Jira::Resource::HasManyProxy,
# # which behaves exactly like an array of
# # Jira::Resource::Child
#
# The following options can be used to override the default behaviour of the
# relationship:
#
# [:attribute_key] The relationship will by default reference a JSON key on the
# object with the same name as the relationship.
#
# has_many :children # => {"id":"123",{"children":[{"id":"456"},{"id":"789"}]}}
#
# Use this option if the key in the JSON is named differently.
#
# # Respond to resource.children, but return the value of resource.attrs['kids']
# has_many :children, :attribute_key => 'kids' # => {"id":"123",{"kids":[{"id":"456"},{"id":"789"}]}}
#
# [:class] The class of the child instance will be inferred from the name of the
# relationship. E.g. <tt>has_many :children</tt> will return an instance
# of <tt>JIRA::Resource::HasManyProxy</tt> containing the collection of
# <tt>JIRA::Resource::Child</tt>.
# Use this option to override the inferred class.
#
# has_many :children, :class => JIRA::Resource::Kid
# [:nested_under] In some cases, the JSON return from JIRA is nested deeply for particular
# relationships. This option allows the nesting to be specified.
#
# # Specify a single depth of nesting.
# has_many :children, :nested_under => 'foo'
# # => Looks for {"foo":{"children":{}}}
# # Specify deeply nested JSON
# has_many :children, :nested_under => ['foo', 'bar', 'baz']
# # => Looks for {"foo":{"bar":{"baz":{"children":{}}}}}
def self.has_many(collection, options = {})
attribute_key = options[:attribute_key] || collection.to_s
child_class = options[:class] || ('JIRA::Resource::' + collection.to_s.classify).constantize
self_class_basename = name.split('::').last.downcase.to_sym
define_method(collection) do
child_class_options = { self_class_basename => self }
attribute = maybe_nested_attribute(attribute_key, options[:nested_under]) || []
collection = attribute.map do |child_attributes|
child_class.new(client, child_class_options.merge(attrs: child_attributes))
end
HasManyProxy.new(self, child_class, collection)
end
end
def self.belongs_to_relationships
@belongs_to_relationships ||= []
end
def self.belongs_to(resource)
belongs_to_relationships.push(resource)
attr_reader resource
attr_reader "#{resource}_id"
end
def self.collection_attributes_are_nested
@collection_attributes_are_nested ||= false
end
def self.nested_collections(value)
@collection_attributes_are_nested = value
end
def id
attrs['id']
end
# Returns a symbol for the given instance, for example
# JIRA::Resource::Issue returns :issue
def to_sym
self.class.endpoint_name.to_sym
end
# Checks if method_name is set in the attributes hash
# and returns true when found, otherwise proxies the
# call to the superclass.
def respond_to?(method_name, _include_all = false)
if attrs.key?(method_name.to_s)
true
else
super(method_name)
end
end
# Overrides method_missing to check the attribute hash
# for resources matching method_name and proxies the call
# to the superclass if no match is found.
def method_missing(method_name, *_args)
if attrs.key?(method_name.to_s)
attrs[method_name.to_s]
else
super(method_name)
end
end
# Each resource has a unique key attribute, this method returns the value
# of that key for this instance.
def key_value
@attrs[self.class.key_attribute.to_s]
end
def collection_path(prefix = '/')
# Just proxy this to the class method
self.class.collection_path(client, prefix)
end
# This returns the URL path component that is specific to this instance,
# for example for Issue id 123 it returns '/issue/123'. For an unsaved
# issue it returns '/issue'
def path_component
path_component = "/#{self.class.endpoint_name}"
path_component += '/' + key_value if key_value
path_component
end
# Fetches the attributes for the specified resource from JIRA unless
# the resource is already expanded and the optional force reload flag
# is not set
def fetch(reload = false, query_params = {})
return if expanded? && !reload
response = client.get(url_with_query_params(url, query_params))
set_attrs_from_response(response)
@expanded = true
end
# Saves the specified resource attributes by sending either a POST or PUT
# request to JIRA, depending on resource.new_record?
#
# Accepts an attributes hash of the values to be saved. Will throw a
# JIRA::HTTPError if the request fails (response is not HTTP 2xx).
def save!(attrs, path = nil)
path ||= new_record? ? url : patched_url
http_method = new_record? ? :post : :put
response = client.send(http_method, path, attrs.to_json)
set_attrs(attrs, false)
set_attrs_from_response(response)
@expanded = false
true
end
# Saves the specified resource attributes by sending either a POST or PUT
# request to JIRA, depending on resource.new_record?
#
# Accepts an attributes hash of the values to be saved. Will return false
# if the request fails.
def save(attrs, path = url)
begin
save_status = save!(attrs, path)
rescue JIRA::HTTPError => exception
begin
set_attrs_from_response(exception.response) # Merge error status generated by JIRA REST API
rescue JSON::ParserError => parse_exception
set_attrs('exception' => {
'class' => exception.response.class.name,
'code' => exception.response.code,
'message' => exception.response.message
})
end
# raise exception
save_status = false
end
save_status
end
# Sets the attributes hash from a HTTPResponse object from JIRA if it is
# not nil or is not a json response.
def set_attrs_from_response(response)
unless response.body.nil? || (response.body.length < 2)
json = self.class.parse_json(response.body)
set_attrs(json)
end
end
# Set the current attributes from a hash. If clobber is true, any existing
# hash values will be clobbered by the new hash, otherwise the hash will
# be deeply merged into attrs. The target paramater is for internal use only
# and should not be used.
def set_attrs(hash, clobber = true, target = nil)
target ||= @attrs
if clobber
target.merge!(hash)
hash
else
hash.each do |k, v|
if v.is_a?(Hash)
set_attrs(v, clobber, target[k])
else
target[k] = v
end
end
end
end
# Sends a delete request to the JIRA Api and sets the deleted instance
# variable on the object to true.
def delete
client.delete(url)
@deleted = true
end
def has_errors?
respond_to?('errors')
end
def url
prefix = '/'
unless self.class.belongs_to_relationships.empty?
prefix = self.class.belongs_to_relationships.inject(prefix) do |prefix_so_far, relationship|
prefix_so_far.to_s + relationship.to_s + '/' + send("#{relationship}_id").to_s + '/'
end
end
if @attrs['self']
the_url = @attrs['self']
the_url = the_url.sub(@client.options[:site].chomp('/'), '') if @client.options[:site]
the_url
elsif key_value
self.class.singular_path(client, key_value.to_s, prefix)
else
self.class.collection_path(client, prefix)
end
end
# This method fixes issue that there is no / prefix in url. It is happened when we call for instance
# Looks like this issue is actual only in case if you use atlassian sdk your app path is not root (like /jira in example below)
# issue.save() for existing resource.
# As a result we got error 400 from JIRA API:
# [07/Jun/2015:15:32:19 +0400] "PUT jira/rest/api/2/issue/10111 HTTP/1.1" 400 -
# After applying this fix we have normal response:
# [07/Jun/2015:15:17:18 +0400] "PUT /jira/rest/api/2/issue/10111 HTTP/1.1" 204 -
def patched_url
result = url
return result if result.start_with?('/', 'http')
"/#{result}"
end
def to_s
"#<#{self.class.name}:#{object_id} @attrs=#{@attrs.inspect}>"
end
# Returns a JSON representation of the current attributes hash.
def to_json(options = {})
attrs.to_json(options)
end
# Determines if the resource is newly created by checking whether its
# key_value is set. If it is nil, the record is new and the method
# will return true.
def new_record?
key_value.nil?
end
protected
# This allows conditional lookup of possibly nested attributes. Example usage:
#
# maybe_nested_attribute('foo') # => @attrs['foo']
# maybe_nested_attribute('foo', 'bar') # => @attrs['bar']['foo']
# maybe_nested_attribute('foo', ['bar', 'baz']) # => @attrs['bar']['baz']['foo']
#
def maybe_nested_attribute(attribute_name, nested_under = nil)
self.class.maybe_nested_attribute(@attrs, attribute_name, nested_under)
end
def self.maybe_nested_attribute(attributes, attribute_name, nested_under = nil)
return attributes[attribute_name] if nested_under.nil?
if nested_under.instance_of? Array
final = nested_under.inject(attributes) do |parent, key|
break if parent.nil?
parent[key]
end
return nil if final.nil?
final[attribute_name]
else
return attributes[nested_under][attribute_name]
end
end
def url_with_query_params(url, query_params)
self.class.url_with_query_params(url, query_params)
end
def self.url_with_query_params(url, query_params)
if !query_params.empty?
"#{url}?#{hash_to_query_string query_params}"
else
url
end
end
def hash_to_query_string(query_params)
self.class.hash_to_query_string(query_params)
end
def self.hash_to_query_string(query_params)
query_params.map do |k, v|
CGI.escape(k.to_s) + '=' + CGI.escape(v.to_s)
end.join('&')
end
def self.query_params_for_single_fetch(options)
Hash[options.select do |k, _v|
QUERY_PARAMS_FOR_SINGLE_FETCH.include? k
end]
end
def self.query_params_for_search(options)
Hash[options.select do |k, _v|
QUERY_PARAMS_FOR_SEARCH.include? k
end]
end
end
end