Class: AWS::S3::MultipartUpload

Inherits:
Object
  • Object
show all
Includes:
Core::Model
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

Attributes included from Core::Model

#config

Instance Method Summary collapse

Methods included from Core::Model

#client, #config_prefix

Constructor Details

#initialize(object, id, options = {}) ⇒ MultipartUpload

Returns a new instance of MultipartUpload.



27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/aws/s3/multipart_upload.rb', line 27

def initialize(object, id, options = {})
  @id = id
  @object = object

  super

  @completed_parts = {}
  @increment_mutex = Mutex.new
  @completed_mutex = Mutex.new
  @last_part = 0
end

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
 
# File 'lib/aws/s3/multipart_upload.rb', line 112

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

#aborted? ⇒ Boolean

Returns True if the upload has been aborted.

Returns:

  • (Boolean) —

    True if the upload has been aborted.

See Also:



122
123
124
 
# File 'lib/aws/s3/multipart_upload.rb', line 122

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.



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

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.



259
260
261
262
263
264
265
266
 
# File 'lib/aws/s3/multipart_upload.rb', line 259

def close
  return if aborted?
  if 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.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/aws/s3/multipart_upload.rb', line 215

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.version_id
    ObjectVersion.new(object, resp.version_id)
  else
    object
  end
end

#completed_parts ⇒ Object 



275
276
277
278
 
# File 'lib/aws/s3/multipart_upload.rb', line 275

def completed_parts
  @completed_parts.values.
    sort { |a, b| a[:part_number] <=> b[: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

#inspect ⇒ Object 



281
282
283
 
# File 'lib/aws/s3/multipart_upload.rb', line 281

def inspect
  "<#{self.class}:#{object.bucket.name}/#{object.key}:#{id}>"
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.



270
271
272
 
# File 'lib/aws/s3/multipart_upload.rb', line 270

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