Class RightAws::S3
In: lib/s3/right_s3.rb
Parent: Object
RuntimeError AwsError AwsNoChange RightAWSParser RightErrorResponseParser RightHttp2xxParser AcfInterface SqsInterface SqsGen2Interface S3Interface Ec2 SdbInterface RightAwsBase ActiveSdbConnect ActiveSdb SqsGen2 S3 S3Generator Sqs RightDummyParser AWSErrorHandler AwsBenchmarkingBlock AwsUtils RightSaxParserCallback lib/sqs/right_sqs_interface.rb lib/sqs/right_sqs_gen2.rb lib/s3/right_s3.rb lib/acf/right_acf_interface.rb lib/sqs/right_sqs_gen2_interface.rb lib/sqs/right_sqs.rb lib/sdb/right_sdb_interface.rb lib/sdb/active_sdb.rb lib/ec2/right_ec2.rb lib/s3/right_s3_interface.rb lib/awsbase/right_awsbase.rb RightAwsBaseInterface VERSION RightAws dot/m_13_0.png

RightAws::S3 — RightScale‘s Amazon S3 interface

The RightAws::S3 class provides a complete interface to Amazon‘s Simple Storage Service. For explanations of the semantics of each call, please refer to Amazon‘s documentation at developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48

See examples below for the bucket and buckets methods.

Error handling: all operations raise an RightAws::AwsError in case of problems. Note that transient errors are automatically retried.

It is a good way to use domain naming style getting a name for the buckets. See docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingBucket.html about the naming convention for the buckets. This case they can be accessed using a virtual domains.

Let assume you have 3 buckets: ‘awesome-bucket’, ‘awesome_bucket’ and ‘AWEsomE-bucket’. The first ones objects can be accessed as: http:// awesome-bucket.s3.amazonaws.com/key/object

But the rest have to be accessed as: http:// s3.amazonaws.com/awesome_bucket/key/object and http:// s3.amazonaws.com/AWEsomE-bucket/key/object

See: docs.amazonwebservices.com/AmazonS3/2006-03-01/VirtualHosting.html for better explanation.

Methods

bucket   buckets   new  

Classes and Modules

Class RightAws::S3::Bucket
Class RightAws::S3::Grantee
Class RightAws::S3::Key
Class RightAws::S3::Owner

Attributes

interface  [R] 

Public Class methods

Create a new handle to an S3 account. All handles share the same per process or per thread HTTP connection to Amazon S3. Each handle is for a specific account. The params are passed through as-is to RightAws::S3Interface.new

Params is a hash:

   {:server       => 's3.amazonaws.com'   # Amazon service host: 's3.amazonaws.com'(default)
    :port         => 443                  # Amazon service port: 80 or 443(default)
    :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
    :multi_thread => true|false           # Multi-threaded (connection per each thread): true or false(default)
    :logger       => Logger Object}       # Logger instance: logs to STDOUT if omitted }

[Source]

    # File lib/s3/right_s3.rb, line 64
64:     def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
65:       @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
66:     end

Public Instance methods

Retrieve an individual bucket. If the bucket does not exist and create is set, a new bucket is created on S3. Launching this method with create=true may affect on the bucket‘s ACL if the bucket already exists. Returns a RightAws::S3::Bucket instance or nil if the bucket does not exist and create is not set.

 s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key)
 bucket1 = s3.bucket('my_awesome_bucket_1')
 bucket1.keys  #=> exception here if the bucket does not exists
  ...
 bucket2 = s3.bucket('my_awesome_bucket_2', true)
 bucket2.keys  #=> list of keys
 # create a bucket at the European location with public read access
 bucket3 = s3.bucket('my-awesome-bucket-3', true, 'public-read', :location => :eu)

 see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
 (section: Canned Access Policies)

[Source]

     # File lib/s3/right_s3.rb, line 100
100:     def bucket(name, create=false, perms=nil, headers={})
101:       headers['x-amz-acl'] = perms if perms
102:       @interface.create_bucket(name, headers) if create
103:       buckets.each { |bucket| return bucket if bucket.name == name }
104:       nil
105:     end

Retrieve a list of buckets. Returns an array of RightAws::S3::Bucket instances.

 # Create handle to S3 account
 s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key)
 my_buckets_names = s3.buckets.map{|b| b.name}
 puts "Buckets on S3: #{my_bucket_names.join(', ')}"

[Source]

    # File lib/s3/right_s3.rb, line 74
74:     def buckets
75:       @interface.list_all_my_buckets.map! do |entry|
76:         owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
77:         Bucket.new(self, entry[:name], entry[:creation_date], owner)
78:       end
79:     end

[Validate]