Parent

Files

RightAws::S3::Key

Attributes

bucket[R]
data[W]
e_tag[R]
headers[RW]
last_modified[R]
meta_headers[RW]
name[R]
owner[R]
size[R]
storage_class[R]

Public Class Methods

add_meta_prefix(meta_headers, prefix=S3Interface::AMAZON_METADATA_PREFIX) click to toggle source
# File lib/s3/right_s3.rb, line 395
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={}) click to toggle source

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
# File lib/s3/right_s3.rb, line 417
def self.create(bucket, name, data=nil, meta_headers={})
  new(bucket, name, data, {}, meta_headers)
end
new(bucket, name, data=nil, headers={}, meta_headers={}, last_modified=nil, e_tag=nil, size=nil, storage_class=nil, owner=nil) click to toggle source

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.

# File lib/s3/right_s3.rb, line 425
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

Public Instance Methods

content_type() click to toggle source

Getter for the 'content-type' metadata

# File lib/s3/right_s3.rb, line 478
def content_type
  @headers['content-type'] if @headers
end
copy(new_key_or_name) click to toggle source

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
# File lib/s3/right_s3.rb, line 581
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
data() click to toggle source

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.

# File lib/s3/right_s3.rb, line 472
def data
  get if !@data and exists?
  @data
end
decoded_meta_headers(key = nil) click to toggle source

Helper to get and URI-decode a header metadata. Metadata have to be HTTP encoded (rfc2616) as we use the Amazon S3 REST api see docs.amazonwebservices.com/AmazonS3/latest/index.html?UsingMetadata.html

# File lib/s3/right_s3.rb, line 485
def decoded_meta_headers(key = nil)
  if key
    # Get one metadata value by its key
    URI.decode(@meta_headers[key.to_s])
  else
    # Get a hash of all metadata with a decoded value
    @decoded_meta_headers ||= begin
      metadata = {}
      @meta_headers.each do |key, value|
        metadata[key.to_sym] = URI.decode(value)
      end
      metadata
    end
  end
end
delete() click to toggle source

Remove key from bucket. Returns true.

key.delete #=> true
# File lib/s3/right_s3.rb, line 687
def delete
  raise 'Key name must be specified.' if @name.right_blank?
  @bucket.s3.interface.delete(@bucket, @name) 
end
exists?() click to toggle source

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
# File lib/s3/right_s3.rb, line 678
def exists?
  @bucket.key(self).last_modified ? true : false
end
full_name(separator='/') click to toggle source

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

key.full_name #=> 'my_awesome_bucket/cool_key'
# File lib/s3/right_s3.rb, line 456
def full_name(separator='/')
  "#{@bucket.to_s}#{separator}#{@name}"
end
get(headers={}) click to toggle source

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

# File lib/s3/right_s3.rb, line 504
def get(headers={})
  response = @bucket.s3.interface.get(@bucket.name, @name, headers)
  @data    = response[:object]
  @headers, @meta_headers = self.class.split_meta(response[:headers])
  refresh(false)
  @data
end
grantees() click to toggle source

Return a list of grantees.

# File lib/s3/right_s3.rb, line 694
def grantees
  Grantee::grantees(self)
end
head() click to toggle source

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

key.meta_headers #=> {"family"=>"qwerty"}
key.head         #=> true
key.meta_headers #=> {"family"=>"qwerty", "name"=>"asdfg"}
# File lib/s3/right_s3.rb, line 645
def head
  @headers, @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name))
  true
end
move(new_key_or_name) click to toggle source

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
# File lib/s3/right_s3.rb, line 605
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
put(data=nil, perms=nil, headers={}, &blck) click to toggle source

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
# File lib/s3/right_s3.rb, line 522
def put(data=nil, perms=nil, headers={}, &blck)
  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), &blck)
end
put_multipart(data=nil, perms=nil, headers={}, part_size=nil) click to toggle source

Store object data on S3 using the Multipart Upload API. This is useful if you do not know the file size upfront (for example reading from pipe or socket) or if you are transmitting data over an unreliable network.

Parameter data is an object which responds to :read or an object which can be converted to a String prior to upload. Parameter part_size determines the size of each part sent (must be > 5MB per Amazon's API requirements)

If data is a stream the caller is responsible for calling close() on the stream after this methods returns

Returns true.

upload_data = StringIO.new('My sample data')
key = RightAws::S3::Key.create(bucket, 'logs/today/1.log')
key.data = upload_data
key.put_multipart(:part_size => 5*1024*1024)             #=> true
# File lib/s3/right_s3.rb, line 544
def put_multipart(data=nil, perms=nil, headers={}, part_size=nil)
  headers['x-amz-acl'] = perms if perms
  @data = data || @data
  meta  = self.class.add_meta_prefix(@meta_headers)
  @bucket.s3.interface.store_object_multipart({:bucket => @bucket.name, :key => @name, :data => @data, :headers => meta.merge(headers), :part_size => part_size})
end
refresh(head=true) click to toggle source

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"}
# File lib/s3/right_s3.rb, line 622
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() click to toggle source

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

key.reload_meta   #=> {"family"=>"qwerty", "name"=>"asdfg"}
# File lib/s3/right_s3.rb, line 654
def reload_meta
  @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name)).last
end
rename(new_name) click to toggle source

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
# File lib/s3/right_s3.rb, line 558
def rename(new_name)
  @bucket.s3.interface.rename(@bucket.name, @name, new_name)
  @name = new_name
end
save_meta(meta_headers) click to toggle source

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"}
# File lib/s3/right_s3.rb, line 664
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() click to toggle source

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'
# File lib/s3/right_s3.rb, line 448
def to_s
  @name.to_s
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.