Class: RightAws::S3::Key

add_meta_prefix(meta_headers, prefix=S3Interface::AMAZON_METADATA_PREFIX)

     # File lib/s3/right_s3.rb, line 382
382:       def self.add_meta_prefix(meta_headers, prefix=S3Interface::AMAZON_METADATA_PREFIX)
383:         meta = {}
384:         meta_headers.each do |meta_header, value|
385:           if meta_header[/#{prefix}/]
386:             meta[meta_header] = value
387:           else
388:             meta["#{S3Interface::AMAZON_METADATA_PREFIX}#{meta_header}"] = value
389:           end
390:         end
391:         meta
392:       end

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

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

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

[Source]

     # File lib/s3/right_s3.rb, line 404
404:       def self.create(bucket, name, data=nil, meta_headers={})
405:         new(bucket, name, data, {}, meta_headers)
406:       end

new(bucket, name, data=nil, headers={}, meta_headers={}, last_modified=nil, e_tag=nil, size=nil, storage_class=nil, owner=nil)

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

[Source]

     # File lib/s3/right_s3.rb, line 412
412:       def initialize(bucket, name, data=nil, headers={}, meta_headers={}, 
413:                      last_modified=nil, e_tag=nil, size=nil, storage_class=nil, owner=nil)
414:         raise 'Bucket must be a Bucket instance.' unless bucket.is_a?(Bucket)
415:         @bucket        = bucket
416:         @name          = name
417:         @data          = data
418:         @e_tag         = e_tag
419:         @size          = size.to_i
420:         @storage_class = storage_class
421:         @owner         = owner
422:         @last_modified = last_modified
423:         if @last_modified && !@last_modified.is_a?(Time) 
424:           @last_modified = Time.parse(@last_modified)
425:         end
426:         @headers, @meta_headers = self.class.split_meta(headers)
427:         @meta_headers.merge!(meta_headers)
428:       end

copy(new_key_or_name)

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

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

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

[Source]

     # File lib/s3/right_s3.rb, line 522
522:       def copy(new_key_or_name)
523:         new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
524:         @bucket.s3.interface.copy(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
525:         new_key_or_name
526:       end

data()

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.

[Source]

     # File lib/s3/right_s3.rb, line 459
459:       def data
460:         get if !@data and exists?
461:         @data
462:       end

delete()

Remove key from bucket. Returns true.

 key.delete #=> true

[Source]

     # File lib/s3/right_s3.rb, line 628
628:       def delete
629:         raise 'Key name must be specified.' if @name.blank?
630:         @bucket.s3.interface.delete(@bucket, @name) 
631:       end

exists?()

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

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

[Source]

     # File lib/s3/right_s3.rb, line 619
619:       def exists?
620:         @bucket.key(self).last_modified ? true : false
621:       end

full_name(separator='/')

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

 key.full_name #=> 'my_awesome_bucket/cool_key'

[Source]

     # File lib/s3/right_s3.rb, line 443
443:       def full_name(separator='/')
444:         "#{@bucket.to_s}#{separator}#{@name}"
445:       end

get(headers={})

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

[Source]

     # File lib/s3/right_s3.rb, line 467
467:       def get(headers={})
468:         response = @bucket.s3.interface.get(@bucket.name, @name, headers)
469:         @data    = response[:object]
470:         @headers, @meta_headers = self.class.split_meta(response[:headers])
471:         refresh(false)
472:         @data
473:       end

grantees()

Return a list of grantees.

[Source]

     # File lib/s3/right_s3.rb, line 635
635:       def grantees
636:         Grantee::grantees(self)
637:       end

head()

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

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

[Source]

     # File lib/s3/right_s3.rb, line 586
586:       def head
587:         @headers, @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name))
588:         true
589:       end

move(new_key_or_name)

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

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

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

[Source]

     # File lib/s3/right_s3.rb, line 546
546:       def move(new_key_or_name)
547:         new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
548:         @bucket.s3.interface.move(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
549:         new_key_or_name
550:       end

public_link()

Return a public link to a key.

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

[Source]

     # File lib/s3/right_s3.rb, line 451
451:       def public_link
452:         params = @bucket.s3.interface.params
453:         "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name('/')}"
454:       end

put(data=nil, perms=nil, headers={})

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

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

[Source]

     # File lib/s3/right_s3.rb, line 485
485:       def put(data=nil, perms=nil, headers={})
486:         headers['x-amz-acl'] = perms if perms
487:         @data = data || @data
488:         meta  = self.class.add_meta_prefix(@meta_headers)
489:         @bucket.s3.interface.put(@bucket.name, @name, @data, meta.merge(headers))
490:       end

refresh(head=true)

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 = RightAws::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"}

[Source]

     # File lib/s3/right_s3.rb, line 563
563:       def refresh(head=true)
564:         new_key        = @bucket.key(self)
565:         @last_modified = new_key.last_modified
566:         @e_tag         = new_key.e_tag
567:         @size          = new_key.size
568:         @storage_class = new_key.storage_class
569:         @owner         = new_key.owner
570:         if @last_modified
571:           self.head
572:           true
573:         else
574:           @headers = @meta_headers = {}
575:           false
576:         end
577:       end

reload_meta()

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

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

[Source]

     # File lib/s3/right_s3.rb, line 595
595:       def reload_meta
596:         @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name)).last
597:       end

rename(new_name)

Rename an object. Returns new object name.

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

[Source]

     # File lib/s3/right_s3.rb, line 499
499:       def rename(new_name)
500:         @bucket.s3.interface.rename(@bucket.name, @name, new_name)
501:         @name = new_name
502:       end

save_meta(meta_headers)

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"}

[Source]

     # File lib/s3/right_s3.rb, line 605
605:       def save_meta(meta_headers)
606:         meta = self.class.add_meta_prefix(meta_headers)
607:         @bucket.s3.interface.copy(@bucket.name, @name, @bucket.name, @name, :replace, meta)
608:         @meta_headers = self.class.split_meta(meta)[1]
609:       end

to_s()

Return key name as a String.

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

[Source]

     # File lib/s3/right_s3.rb, line 435
435:       def to_s
436:         @name.to_s
437:       end

Methods

Attributes

Public Class methods

Public Instance methods