Class: Aws::S3::Key

Inherits:
Object show all
Defined in:
lib/s3/right_s3.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(bucket, name, data = nil, headers = {}, meta_headers = {}, last_modified = nil, e_tag = nil, size = nil, storage_class = nil, owner = nil) ⇒ Key

Create a new Key instance, but do not create the actual key. In normal use this method should not be called directly. Use Aws::S3::Key.create or bucket.key() instead.



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/s3/right_s3.rb', line 424

def initialize(bucket, name, data=nil, headers={}, meta_headers={},
        last_modified=nil, e_tag=nil, size=nil, storage_class=nil, owner=nil)
    raise 'Bucket must be a Bucket instance.' unless bucket.is_a?(Bucket)
    @bucket        = bucket
    @name          = name
    @data          = data
    @e_tag         = e_tag
    @size          = size.to_i
    @storage_class = storage_class
    @owner         = owner
    @last_modified = last_modified
    if @last_modified && !@last_modified.is_a?(Time)
        @last_modified = Time.parse(@last_modified)
    end
    @headers, @meta_headers = self.class.split_meta(headers)
    @meta_headers.merge!(meta_headers)
end

Instance Attribute Details

#bucket ⇒ Object (readonly)

Returns the value of attribute bucket.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def bucket
  @bucket
end

#data ⇒ Object

Return Key data. Retrieve this data from Amazon if it is the first time call. TODO TRB 6/19/07 What does the above mean? Clarify.



471
472
473
474
 
# File 'lib/s3/right_s3.rb', line 471

def data
    get if !@data and exists?
    @data
end

#e_tag ⇒ Object (readonly)

Returns the value of attribute e_tag.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def e_tag
  @e_tag
end

#headers ⇒ Object

Returns the value of attribute headers.



378
379
380
 
# File 'lib/s3/right_s3.rb', line 378

def headers
  @headers
end

#last_modified ⇒ Object (readonly)

Returns the value of attribute last_modified.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def last_modified
  @last_modified
end

#meta_headers ⇒ Object

Returns the value of attribute meta_headers.



378
379
380
 
# File 'lib/s3/right_s3.rb', line 378

def meta_headers
  @meta_headers
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def name
  @name
end

#owner ⇒ Object (readonly)

Returns the value of attribute owner.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def owner
  @owner
end

#size ⇒ Object (readonly)

Returns the value of attribute size.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def size
  @size
end

#storage_class ⇒ Object (readonly)

Returns the value of attribute storage_class.



377
378
379
 
# File 'lib/s3/right_s3.rb', line 377

def storage_class
  @storage_class
end

Class Method Details

.add_meta_prefix(meta_headers, prefix = S3Interface::AMAZON_METADATA_PREFIX) ⇒ Object 



394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/s3/right_s3.rb', line 394

def self.add_meta_prefix(meta_headers, prefix=S3Interface::AMAZON_METADATA_PREFIX)
    meta = {}
    meta_headers.each do |meta_header, value|
        if meta_header[/#{prefix}/]
            meta[meta_header] = value
        else
            meta["#{S3Interface::AMAZON_METADATA_PREFIX}#{meta_header}"] = value
        end
    end
    meta
end

.create(bucket, name, data = nil, meta_headers = {}) ⇒ Object

Create a new Key instance, but do not create the actual key. The name is a String. Returns a new Key instance.

key = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key.exists?                                                  #=> true | false
key.put('Woohoo!')                                           #=> true
key.exists?                                                  #=> true



416
417
418
 
# File 'lib/s3/right_s3.rb', line 416

def self.create(bucket, name, data=nil, meta_headers={})
    new(bucket, name, data, {}, meta_headers)
end

.split_meta(headers) ⇒ Object

Separate Amazon meta headers from other headers



382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/s3/right_s3.rb', line 382

def self.split_meta(headers) #:nodoc:
    hash = headers.dup
    meta = {}
    hash.each do |key, value|
        if key[/^#{S3Interface::AMAZON_METADATA_PREFIX}/]
            meta[key.gsub(S3Interface::AMAZON_METADATA_PREFIX, '')] = value
            hash.delete(key)
        end
    end
    [hash, meta]
end

Instance Method Details

#copy(new_key_or_name) ⇒ Object

Create an object copy. Returns a destination Aws::S3::Key instance.

# Key instance as destination
key1 = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key2 = Aws::S3::Key.create(bucket, 'logs/today/2.log') #=> #<Aws::S3::Key:0xb7b5e240 ... >
key1.put('Olala!')   #=> true
key1.copy(key2)      #=> #<Aws::S3::Key:0xb7b5e240 ... >
key1.exists?         #=> true
key2.exists?         #=> true
puts key2.data       #=> 'Olala!'

# String as destination
key = Aws::S3::Key.create(bucket, 'logs/today/777.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key.put('Olala!')                          #=> true
new_key = key.copy('logs/today/888.log')   #=> #<Aws::S3::Key:0xb7b5e240 ... >
key.exists?                                #=> true
new_key.exists?                            #=> true



534
535
536
537
538
 
# File 'lib/s3/right_s3.rb', line 534

def copy(new_key_or_name)
    new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
    @bucket.s3.interface.copy(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
    new_key_or_name
end

#delete ⇒ Object

Remove key from bucket. Returns true.

key.delete #=> true



640
641
642
643
 
# File 'lib/s3/right_s3.rb', line 640

def delete
    raise 'Key name must be specified.' if @name.blank?
    @bucket.s3.interface.delete(@bucket, @name)
end

#exists? ⇒ Boolean

Check for existence of the key in the given bucket. Returns true or false.

key = Aws::S3::Key.create(bucket,'logs/today/1.log')
key.exists?        #=> false
key.put('Woohoo!') #=> true
key.exists?        #=> true

Returns:

  • (Boolean) 


631
632
633
 
# File 'lib/s3/right_s3.rb', line 631

def exists?
    @bucket.key(self).last_modified ? true : false
end

#full_name(separator = '/') ⇒ Object

Return the full S3 path to this key (bucket/key).

key.full_name #=> 'my_awesome_bucket/cool_key'



455
456
457
 
# File 'lib/s3/right_s3.rb', line 455

def full_name(separator='/')
    "#{@bucket.to_s}#{separator}#{@name}"
end

#get(headers = {}, &block) ⇒ Object

Retrieve object data and attributes from Amazon. Returns a String.



479
480
481
482
483
484
485
 
# File 'lib/s3/right_s3.rb', line 479

def get(headers={}, &block)
    response = @bucket.s3.interface.get(@bucket.name, @name, headers, &block)
    @data    = response[:object]
    @headers, @meta_headers = self.class.split_meta(response[:headers])
#        refresh(false) Holy moly, this was doing two extra hits to s3 for making 3 hits for every get!!
    @data
end

#grantees ⇒ Object

Return a list of grantees.



647
648
649
 
# File 'lib/s3/right_s3.rb', line 647

def grantees
    Grantee::grantees(self)
end

#head ⇒ Object

Updates headers and meta-headers from S3. Returns true.

key.meta_headers #=> {"family"=>"qwerty"}
key.head         #=> true
key.meta_headers #=> {"family"=>"qwerty", "name"=>"asdfg"}



598
599
600
601
 
# File 'lib/s3/right_s3.rb', line 598

def head
    @headers, @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name))
    true
end

#move(new_key_or_name) ⇒ Object

Move an object to other location. Returns a destination Aws::S3::Key instance.

# Key instance as destination
key1 = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key2 = Aws::S3::Key.create(bucket, 'logs/today/2.log') #=> #<Aws::S3::Key:0xb7b5e240 ... >
key1.put('Olala!')   #=> true
key1.move(key2)      #=> #<Aws::S3::Key:0xb7b5e240 ... >
key1.exists?         #=> false
key2.exists?         #=> true
puts key2.data       #=> 'Olala!'

# String as destination
key = Aws::S3::Key.create(bucket, 'logs/today/777.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key.put('Olala!')                          #=> true
new_key = key.move('logs/today/888.log')   #=> #<Aws::S3::Key:0xb7b5e240 ... >
key.exists?                                #=> false
new_key.exists?                            #=> true



558
559
560
561
562
 
# File 'lib/s3/right_s3.rb', line 558

def move(new_key_or_name)
    new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
    @bucket.s3.interface.move(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
    new_key_or_name
end

#public_link ⇒ Object

Return a public link to a key.

key.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket/cool_key'



463
464
465
466
 
# File 'lib/s3/right_s3.rb', line 463

def public_link
    params = @bucket.s3.interface.params
    "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name('/')}"
end

#put(data = nil, perms = nil, headers = {}) ⇒ Object

Store object data on S3. Parameter data is a String or S3Object instance. Returns true.

key = Aws::S3::Key.create(bucket, 'logs/today/1.log')
key.data = 'Qwerty'
key.put             #=> true
 ...
key.put('Olala!')   #=> true



497
498
499
500
501
502
 
# File 'lib/s3/right_s3.rb', line 497

def put(data=nil, perms=nil, headers={})
    headers['x-amz-acl'] = perms if perms
    @data = data || @data
    meta  = self.class.add_meta_prefix(@meta_headers)
    @bucket.s3.interface.put(@bucket.name, @name, @data, meta.merge(headers))
end

#refresh(head = true) ⇒ Object

Retrieve key info from bucket and update attributes. Refresh meta-headers (by calling head method) if head is set. Returns true if the key exists in bucket and false otherwise.

key = Aws::S3::Key.create(bucket, 'logs/today/1.log')
key.e_tag        #=> nil
key.meta_headers #=> {}
key.refresh      #=> true
key.e_tag        #=> '12345678901234567890bf11094484b6'
key.meta_headers #=> {"family"=>"qwerty", "name"=>"asdfg"}



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
 
# File 'lib/s3/right_s3.rb', line 575

def refresh(head=true)
    new_key        = @bucket.key(self)
    @last_modified = new_key.last_modified
    @e_tag         = new_key.e_tag
    @size          = new_key.size
    @storage_class = new_key.storage_class
    @owner         = new_key.owner
    if @last_modified
        self.head
        true
    else
        @headers = @meta_headers = {}
        false
    end
end

#reload_meta ⇒ Object

Reload meta-headers only. Returns meta-headers hash.

key.reload_meta   #=> {"family"=>"qwerty", "name"=>"asdfg"}



607
608
609
 
# File 'lib/s3/right_s3.rb', line 607

def reload_meta
    @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name)).last
end

#rename(new_name) ⇒ Object

Rename an object. Returns new object name.

key = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
key.rename('logs/today/2.log')   #=> 'logs/today/2.log'
puts key.name                    #=> 'logs/today/2.log'
key.exists?                      #=> true



511
512
513
514
 
# File 'lib/s3/right_s3.rb', line 511

def rename(new_name)
    @bucket.s3.interface.rename(@bucket.name, @name, new_name)
    @name = new_name
end

#save_meta(meta_headers) ⇒ Object

Replace meta-headers by new hash at S3. Returns new meta-headers hash.

key.reload_meta   #=> {"family"=>"qwerty", "name"=>"asdfg"}
key.save_meta     #=> {"family"=>"oops", "race" => "troll"}
key.reload_meta   #=> {"family"=>"oops", "race" => "troll"}



617
618
619
620
621
 
# File 'lib/s3/right_s3.rb', line 617

def save_meta(meta_headers)
    meta          = self.class.add_meta_prefix(meta_headers)
    @bucket.s3.interface.copy(@bucket.name, @name, @bucket.name, @name, :replace, meta)
    @meta_headers = self.class.split_meta(meta)[1]
end

#to_s ⇒ Object

Return key name as a String.

key = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... >
puts key                                                   #=> 'logs/today/1.log'



447
448
449
 
# File 'lib/s3/right_s3.rb', line 447

def to_s
    @name.to_s
end