Class: JIRA::Resource::Attachment

Inherits:
Base
  • Object
show all
Defined in:
lib/jira/resource/attachment.rb

Overview

This class provides the Attachment object <-> REST mapping for JIRA::Resource::Attachment derived class, i.e. the Create, Retrieve, Update, Delete lifecycle methods.

Lifecycle methods

Retrieving a single attachment by Issue and attachment id

# Find attachment with id 30076 on issue SUP-3000.
issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
attachment = issue.attachments.find do |attachment_curr|
    30076 == attachment_curr.id.to_i
end

Retrieving meta information for an attachments

attachment.meta

Retrieving file contents of attachment

content = URI.open(attachment.content).read
content = attachment.download_contents
content = attachment.download_file { |file| file.read }

Adding an attachment to an issue

Dir.mktmpdir do |dir|
  path = File.join(dir, filename)
  IO.copy_stream(file.path, path)

  issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  attachment = issue.attachments.build
  attachment.save!( { file: path, mimeType: content_type } )
end

Deleting an attachment

attachment.delete

Constant Summary

Constants inherited from Base

Base::QUERY_PARAMS_FOR_SEARCH, Base::QUERY_PARAMS_FOR_SINGLE_FETCH

Instance Attribute Summary collapse

Attributes inherited from Base

#attrs, #client, #deleted, #expanded

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

all, belongs_to, belongs_to_relationships, build, collection_attributes_are_nested, collection_path, #collection_path, #delete, #fetch, find, #has_errors?, has_many, has_one, #id, #initialize, key_attribute, #key_value, #method_missing, nested_collections, #new_record?, parse_json, #patched_url, #path_component, #respond_to?, #set_attrs, #set_attrs_from_response, singular_path, #to_json, #to_s, #to_sym, #url

Constructor Details

This class inherits a constructor from JIRA::Base

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class JIRA::Base

Instance Attribute Details

#author ⇒ JIRA::Resource::User (readonly)

Returns the user who created the attachment.

Returns:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#content ⇒ String (readonly)

Returns URL (not the contents) to download the contents of the attachment.

Returns:

  • (String) —

    URL (not the contents) to download the contents of the attachment



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#created ⇒ String (readonly)

Returns timestamp when the attachment was created.

Returns:

  • (String) —

    timestamp when the attachment was created



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#filename ⇒ String (readonly)

Returns the filename.

Returns:

  • (String) —

    the filename



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#mimeType ⇒ String (readonly)

Returns MIME of the content type.

Returns:

  • (String) —

    MIME of the content type



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#self ⇒ String (readonly)

Returns URL to JSON of this attachment.

Returns:

  • (String) —

    URL to JSON of this attachment



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#size ⇒ Integer (readonly)

Returns the file size.

Returns:

  • (Integer) —

    the file size



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#thumbnail ⇒ String (readonly)

Returns URL to download the thumbnail of the attachment.

Returns:

  • (String) —

    URL to download the thumbnail of the attachment



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

Class Method Details

.meta(client) ⇒ Hash

Gets metadata about attachments on the server.

Examples:

Return metadata

Attachment.meta(client)
=>  { "enabled" => true, "uploadLimit" => 1000000 }

Returns:

  • (Hash) —

    The metadata for attachments. (See example.)



91
92
93
94
 
# File 'lib/jira/resource/attachment.rb', line 91

def self.meta(client)
  response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
  parse_json(response.body)
end

Instance Method Details

#download_contents(headers = {}) ⇒ String, NilClass

Downloads the file contents as a string object.

Note that this reads the contents into a ruby string in memory. A file might be very large so it is recommended to avoid this unless you are certain about doing so. Use the download_file method instead and avoid calling the read method without a limit.

Examples:

Save file contents to a string.

content = download_contents

Parameters:

  • headers (Hash) (defaults to: {}) —

    Any additional headers to call Jira.

Returns:

  • (String, NilClass) —

    The file contents.



131
132
133
 
# File 'lib/jira/resource/attachment.rb', line 131

def download_contents(headers = {})
  download_file(headers, &:read)
end

#download_file(headers = {}) {|file| ... } ⇒ Object

Opens a file streaming the download of the attachment.

Examples:

Write file contents to a file.

File.open('some-filename', 'wb') do |output|
  download_file do |file|
    IO.copy_stream(file, output)
  end
end

Stream file contents for an HTTP response.

response.headers[ "Content-Type" ] = "application/octet-stream"
download_file do |file|
  chunk = file.read(8000)
  while chunk.present? do
    response.stream.write(chunk)
    chunk = file.read(8000)
  end
end
response.stream.close

Parameters:

  • headers (Hash) (defaults to: {}) —

    Any additional headers to call Jira.

Yields:

  • |file|

Yield Parameters:

  • file (IO) —

    The IO object streaming the download.



116
117
118
119
 
# File 'lib/jira/resource/attachment.rb', line 116

def download_file(headers = {}, &)
  default_headers = client.options[:default_headers]
  URI.parse(content).open(default_headers.merge(headers), &)
end

#save(attrs, path = url) ⇒ Boolean

Uploads a file as an attachment to its issue.

Filename used will be the basename of the given file.

Parameters:

  • attrs (Hash) —

    the options to create a message with.

Options Hash (attrs):

  • :file (IO, String) —

    The file to upload, either a file object or a file path to find the file.

  • :mimeType (String) —

    The MIME type of the file.

Returns:

  • (Boolean) —

    True if successful, false if failed.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jira/resource/attachment.rb', line 77

class Attachment < JIRA::Base
  belongs_to :issue
  has_one :author, class: JIRA::Resource::User

  # @private
  def self.endpoint_name
    'attachments'
  end

  # Gets metadata about attachments on the server.
  # @example Return metadata
  #   Attachment.meta(client)
  #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
  # @return [Hash] The metadata for attachments.  (See example.)
  def self.meta(client)
    response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
    parse_json(response.body)
  end

  # Opens a file streaming the download of the attachment.
  # @example Write file contents to a file.
  #   File.open('some-filename', 'wb') do |output|
  #     download_file do |file|
  #       IO.copy_stream(file, output)
  #     end
  #   end
  # @example Stream file contents for an HTTP response.
  #   response.headers[ "Content-Type" ] = "application/octet-stream"
  #   download_file do |file|
  #     chunk = file.read(8000)
  #     while chunk.present? do
  #       response.stream.write(chunk)
  #       chunk = file.read(8000)
  #     end
  #   end
  #   response.stream.close
  # @param [Hash] headers Any additional headers to call Jira.
  # @yield |file|
  # @yieldparam [IO] file The IO object streaming the download.
  def download_file(headers = {}, &)
    default_headers = client.options[:default_headers]
    URI.parse(content).open(default_headers.merge(headers), &)
  end

  # Downloads the file contents as a string object.
  #
  # Note that this reads the contents into a ruby string in memory.
  # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
  # Use the download_file method instead and avoid calling the read method without a limit.
  #
  # @example Save file contents to a string.
  #   content = download_contents
  # @param [Hash] headers Any additional headers to call Jira.
  # @return [String,NilClass] The file contents.
  def download_contents(headers = {})
    download_file(headers, &:read)
  end

  # Uploads a file as an attachment to its issue.
  #
  # Filename used will be the basename of the given file.
  #
  # @example Save a file as an attachment
  #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
  #   attachment = issue.attachments.build
  #   attachment.save!( { file: path, mimeType: 'text/plain' } )
  # @param [Hash] attrs the options to create a message with.
  # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
  # @option attrs [String] :mimeType The MIME type of the file.
  # @raise [JIRA::HTTPError] if failed
  def save!(attrs, path = url)
    file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
    mime_type = attrs[:mimeType] || 'application/binary'

    headers = { 'X-Atlassian-Token' => 'nocheck' }
    data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

    response = client.post_multipart(path, data, headers)

    set_attributes(attrs, response)

    @expanded = false
    true
  end

  private

  def set_attributes(attributes, response)
    set_attrs(attributes, false)
    return if response.body.nil? || response.body.length < 2

    json = self.class.parse_json(response.body)
    attachment = json[0]

    set_attrs(attachment)
  end
end

#save!(attrs, path = url) ⇒ Object

Uploads a file as an attachment to its issue.

Filename used will be the basename of the given file.

Examples:

Save a file as an attachment

issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
attachment = issue.attachments.build
attachment.save!( { file: path, mimeType: 'text/plain' } )

Parameters:

  • attrs (Hash) —

    the options to create a message with.

Options Hash (attrs):

  • :file (IO, String) —

    The file to upload, either a file object or a file path to find the file.

  • :mimeType (String) —

    The MIME type of the file.

Raises:



147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/jira/resource/attachment.rb', line 147

def save!(attrs, path = url)
  file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
  mime_type = attrs[:mimeType] || 'application/binary'

  headers = { 'X-Atlassian-Token' => 'nocheck' }
  data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }

  response = client.post_multipart(path, data, headers)

  set_attributes(attrs, response)

  @expanded = false
  true
end