You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

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.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Defined Under Namespace

Classes: EmptyUploadError

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.



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

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.



61
62
63
 
# File 'lib/aws/s3/multipart_upload.rb', line 61

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.



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

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) 


121
122
123
124
125
126
127
 
# File 'lib/aws/s3/multipart_upload.rb', line 121

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:



133
134
135
 
# File 'lib/aws/s3/multipart_upload.rb', line 133

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.



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/aws/s3/multipart_upload.rb', line 191

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, :etag => resp[:etag])
end

#bucket ⇒ Object 



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

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.



297
298
299
300
301
302
303
304
305
 
# File 'lib/aws/s3/multipart_upload.rb', line 297

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.

Raises:



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
278
279
280
281
282
283
284
285
286
 
# File 'lib/aws/s3/multipart_upload.rb', line 253

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 EmptyUploadError.new("Unable to complete an empty upload.") 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



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/aws/s3/multipart_upload.rb', line 225

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, :etag => resp[:etag])
end

#exists? ⇒ Boolean

Returns True if the upload exists.

Returns:

  • (Boolean) —

    True if the upload exists.



74
75
76
77
78
79
80
 
# File 'lib/aws/s3/multipart_upload.rb', line 74

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.



87
88
89
 
# File 'lib/aws/s3/multipart_upload.rb', line 87

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.



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

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.



309
310
311
 
# File 'lib/aws/s3/multipart_upload.rb', line 309

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.



108
109
110
 
# File 'lib/aws/s3/multipart_upload.rb', line 108

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?


102
103
104
 
# File 'lib/aws/s3/multipart_upload.rb', line 102

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