Class: AWS::S3::MultipartUpload

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/s3/multipart_upload.rb

Overview

Represents a multipart upload to an S3 object. See S3Object#multipart_upload for a convenient way to initiate a multipart upload.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#id ⇒ String (readonly) Also known as: upload_id

Returns the upload id.

Returns:

  • (String) —

    Returns the upload id.



47
48
49
 
# File 'lib/aws/s3/multipart_upload.rb', line 47

def id
  @id
end

#object ⇒ S3Object (readonly)

Returns the object this upload is intended for.

Returns:

  • (S3Object) —

    Returns the object this upload is intended for.



52
53
54
 
# File 'lib/aws/s3/multipart_upload.rb', line 52

def object
  @object
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Returns true if both multipart uploads represent the same object and upload.

Returns:

  • (Boolean) —

    Returns true if both multipart uploads represent the same object and upload.



56
57
58
59
60
 
# File 'lib/aws/s3/multipart_upload.rb', line 56

def ==(other)
  other.kind_of?(MultipartUpload) and
    other.object == object and
    other.id == id
end

#abort ⇒ nil Also known as: delete, cancel

Aborts the upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.

Returns:

  • (nil) 


112
113
114
115
116
117
118
 
# File 'lib/aws/s3/multipart_upload.rb', line 112

def abort
  unless aborted?
    client.abort_multipart_upload(base_opts)
    @aborted = true
  end
  nil
end

#aborted? ⇒ Boolean

Returns True if the upload has been aborted.

Returns:

  • (Boolean) —

    True if the upload has been aborted.

See Also:



124
125
126
 
# File 'lib/aws/s3/multipart_upload.rb', line 124

def aborted?
  @aborted
end

#add_part(data, options = {}) ⇒ Object #add_part(options) ⇒ Object

Uploads a part.

Overloads:

  • #add_part(data, options = {}) ⇒ Object

    Parameters:

    • data —

      The data to upload. Valid values include:

      • A string
      • A Pathname object

      • Any object responding to read and eof?; the object must support the following access methods:

        read                     # all at once
read(length) until eof?  # in chunks

        If you specify data this way, you must also include the :content_length option.

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

      Additional options for the upload.

    Options Hash (options):

    • :content_length (Integer) —

      If provided, this option must match the total number of bytes written to S3 during the operation. This option is required if :data is an IO-like object without a size method.

  • #add_part(options) ⇒ Object

    Parameters:

    • options (Hash) —

      Options for the upload. Either :data or :file is required.

    Options Hash (options):

    • :data (Object) —

      The data to upload. Valid values include:

      • A string
      • A Pathname object

      • Any object responding to read and eof?; the object must support the following access methods:

         read                     # all at once
 read(length) until eof?  # in chunks

        If you specify data this way, you must also include the :content_length option.

    • :file (String) —

      Can be specified instead of :data; its value specifies the path of a file to upload.

    • :content_length (Integer) —

      If provided, this option must match the total number of bytes written to S3 during the operation. This option is required if :data is an IO-like object without a size method.

    • :part_number (Integer) —

      The part number.



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/aws/s3/multipart_upload.rb', line 182

def add_part(data_or_options, options = {})
  if data_or_options.kind_of?(Hash)
    part_options = base_opts.merge(data_or_options)
  else
    part_options = base_opts.merge(:data => data_or_options)
  end
  part_options.merge!(options)

  unless part_options[:part_number]
    @increment_mutex.synchronize do
      part_options[:part_number] = (@last_part += 1)
    end
  end
  part_number = part_options[:part_number]

  resp = client.upload_part(part_options)
  @completed_mutex.synchronize do
    @completed_parts[part_number] = {
      :part_number => part_number,
      :etag => resp.etag
    }
  end
  UploadedPart.new(self, part_number)
end

#bucket ⇒ Object 



39
40
41
 
# File 'lib/aws/s3/multipart_upload.rb', line 39

def bucket
  object.bucket
end

#close ⇒ S3Object, ObjectVersion

Completes the upload or aborts it if no parts have been uploaded yet. Does nothing if the upload has already been aborted.

Returns:

  • (S3Object, ObjectVersion) —

    If the bucket has versioning enabled, returns the ObjectVersion representing the version that was uploaded. If versioning is disabled, returns the object. If no upload was attempted (e.g. if it was aborted or if no parts were uploaded), returns nil.



288
289
290
291
292
293
294
295
296
 
# File 'lib/aws/s3/multipart_upload.rb', line 288

def close
  if aborted?
    nil
  elsif completed_parts.empty?
    abort
  else
    complete
  end
end

#complete(*parts) ⇒ S3Object, ObjectVersion

Completes the upload by assembling previously uploaded parts.

Returns:

  • (S3Object, ObjectVersion) —

    If the bucket has versioning enabled, returns the ObjectVersion representing the version that was uploaded. If versioning is disabled, returns the object.



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/aws/s3/multipart_upload.rb', line 244

def complete(*parts)
  parts = parts.flatten
  case parts.first
  when :remote_parts
    complete_opts = get_complete_opts
  when :local_parts, nil
    complete_opts = base_opts.merge(:parts => completed_parts)
  else
    part_numbers = parts.map do |part|
      case part
      when Integer
        part
      when UploadedPart
        raise ArgumentError.new("cannot complete an upload with parts "+
                                "from a different upload") unless
          part.upload == self

        part.part_number
      else
        raise ArgumentError.new("expected number or UploadedPart")
      end
    end
    complete_opts = get_complete_opts(part_numbers)
  end

  raise "no parts uploaded" if complete_opts[:parts].empty?

  resp = client.complete_multipart_upload(complete_opts)
  if resp.data[:version_id]
    ObjectVersion.new(object, resp.data[:version_id])
  else
    object
  end
end

#copy_part(copy_source, options = {}) ⇒ Object

Copies a part.

@param [string] copy_source Full S3 name of source, ie bucket/key

@param [Hash] options Additional options for the copy.

@option options [Integer] :part_number The part number.

@option options [Integer] :copy_source_range Range of bytes to copy, ie bytes=0-45687



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/aws/s3/multipart_upload.rb', line 216

def copy_part(copy_source, options = {})
  part_options = base_opts.merge(options)
  part_options.merge!(:copy_source => copy_source)

  unless part_options[:part_number]
    @increment_mutex.synchronize do
      part_options[:part_number] = (@last_part += 1)
    end
  end
  part_number = part_options[:part_number]

  resp = client.copy_part(part_options)
  @completed_mutex.synchronize do
    @completed_parts[part_number] = {
      :part_number => part_number,
      :etag => resp[:etag]
    }
  end
  UploadedPart.new(self, part_number)
end

#exists? ⇒ Boolean

Returns True if the upload exists.

Returns:

  • (Boolean) —

    True if the upload exists.



65
66
67
68
69
70
71
 
# File 'lib/aws/s3/multipart_upload.rb', line 65

def exists?
  client.list_parts(base_opts)
rescue Errors::NoSuchUpload => e
  false
else
  true
end

#initiator ⇒ Object

Returns The upload initiator. This object will have :id and :display_name methods; if the initiator is an IAM user, the :id method will return the ARN of the user, and if the initiator is an AWS account, this method will return the same data as #owner.

Returns:

  • The upload initiator. This object will have :id and :display_name methods; if the initiator is an IAM user, the :id method will return the ARN of the user, and if the initiator is an AWS account, this method will return the same data as #owner.



78
79
80
 
# File 'lib/aws/s3/multipart_upload.rb', line 78

def initiator
  client.list_parts(base_opts).initiator
end

#owner ⇒ Object

Returns The upload owner. This object will have :id and :display_name methods.

Returns:

  • The upload owner. This object will have :id and :display_name methods.



84
85
86
 
# File 'lib/aws/s3/multipart_upload.rb', line 84

def owner
  client.list_parts(base_opts).owner
end

#parts ⇒ UploadedPartCollection

Returns A collection representing the parts that have been uploaded to S3 for this upload.

Returns:

  • (UploadedPartCollection) —

    A collection representing the parts that have been uploaded to S3 for this upload.



300
301
302
 
# File 'lib/aws/s3/multipart_upload.rb', line 300

def parts
  UploadedPartCollection.new(self)
end

#reduced_redundancy? ⇒ Boolean

Returns True if the uploaded object will be stored with reduced redundancy.

Returns:

  • (Boolean) —

    True if the uploaded object will be stored with reduced redundancy.



99
100
101
 
# File 'lib/aws/s3/multipart_upload.rb', line 99

def reduced_redundancy?
  storage_class == :reduced_redundancy
end

#storage_class ⇒ Symbol

Returns The class of storage used to store the uploaded object. Possible values:

  • :standard
  • :reduced_redundancy?.

Returns:

  • (Symbol) —

    The class of storage used to store the uploaded object. Possible values:

    • :standard
    • :reduced_redundancy?


93
94
95
 
# File 'lib/aws/s3/multipart_upload.rb', line 93

def storage_class
  client.list_parts(base_opts).storage_class.downcase.to_sym
end