lib/s3/right_s3.rb in aws-1.11.38 vs lib/s3/right_s3.rb in aws-2.1.0

- old
+ new

@@ -19,22 +19,22 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -module RightAws +module Aws - # = RightAws::S3 -- RightScale's Amazon S3 interface - # The RightAws::S3 class provides a complete interface to Amazon's Simple + # = Aws::S3 -- RightScale's Amazon S3 interface + # The Aws::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 # http://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 + # Error handling: all operations raise an Aws::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 http://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. @@ -50,11 +50,11 @@ class S3 attr_reader :interface # 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 + # The +params+ are passed through as-is to Aws::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) @@ -64,13 +64,13 @@ def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={}) @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params) end # Retrieve a list of buckets. - # Returns an array of RightAws::S3::Bucket instances. + # Returns an array of Aws::S3::Bucket instances. # # Create handle to S3 account - # s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key) + # s3 = Aws::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(', ')}" def buckets @interface.list_all_my_buckets.map! do |entry| owner = Owner.new(entry[:owner_id], entry[:owner_display_name]) @@ -80,14 +80,14 @@ # 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 + # Returns a Aws::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) + # s3 = Aws::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 @@ -113,19 +113,19 @@ # is created on S3. Launching this method with +create+=+true+ may # affect on the bucket's ACL if the bucket already exists. # Returns 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) + # s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key) # ... - # bucket1 = RightAws::S3::Bucket.create(s3, 'my_awesome_bucket_1') + # bucket1 = Aws::S3::Bucket.create(s3, 'my_awesome_bucket_1') # bucket1.keys #=> exception here if the bucket does not exists # ... - # bucket2 = RightAws::S3::Bucket.create(s3, 'my_awesome_bucket_2', true) + # bucket2 = Aws::S3::Bucket.create(s3, 'my_awesome_bucket_2', true) # bucket2.keys #=> list of keys # # create a bucket at the European location with public read access - # bucket3 = RightAws::S3::Bucket.create(s3,'my-awesome-bucket-3', true, 'public-read', :location => :eu) + # bucket3 = Aws::S3::Bucket.create(s3,'my-awesome-bucket-3', true, 'public-read', :location => :eu) # # see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html # (section: Canned Access Policies) # def self.create(s3, name, create=false, perms=nil, headers={}) @@ -133,11 +133,11 @@ end # Create a bucket instance. In normal use this method should # not be called directly. - # Use RightAws::S3::Bucket.create or RightAws::S3.bucket instead. + # Use Aws::S3::Bucket.create or Aws::S3.bucket instead. def initialize(s3, name, creation_date=nil, owner=nil) @s3 = s3 @name = name @owner = owner @creation_date = creation_date @@ -146,11 +146,11 @@ end end # Return bucket name as a String. # - # bucket = RightAws::S3.bucket('my_awesome_bucket') + # bucket = Aws::S3.bucket('my_awesome_bucket') # puts bucket #=> 'my_awesome_bucket' # def to_s @name.to_s end @@ -241,13 +241,13 @@ # Retrieve key information from Amazon. # The +key_name+ is a +String+ or Key instance. # Retrieves meta-header information if +head+ is +true+. # Returns new Key instance. # - # key = bucket.key('logs/today/1.log', true) #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # key = bucket.key('logs/today/1.log', true) #=> #<Aws::S3::Key:0xb7b1e240 ... > # # is the same as: - # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') + # key = Aws::S3::Key.create(bucket, 'logs/today/1.log') # key.head # def key(key_name, head=false) raise 'Key name can not be empty.' if key_name.blank? key_instance = nil @@ -286,36 +286,36 @@ def get(key, headers={}) key = Key.create(self, key.to_s) unless key.is_a?(Key) key.get(headers) end - # Rename object. Returns RightAws::S3::Key instance. + # Rename object. Returns Aws::S3::Key instance. # - # new_key = bucket.rename_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # new_key = bucket.rename_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... > # puts key.name #=> 'logs/today/2.log' # key.exists? #=> true # def rename_key(old_key_or_name, new_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) old_key_or_name.rename(new_name) old_key_or_name end - # Create an object copy. Returns a destination RightAws::S3::Key instance. + # Create an object copy. Returns a destination Aws::S3::Key instance. # - # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... > # puts key.name #=> 'logs/today/2.log' # key.exists? #=> true # def copy_key(old_key_or_name, new_key_or_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) old_key_or_name.copy(new_key_or_name) end - # Move an object to other location. Returns a destination RightAws::S3::Key instance. + # Move an object to other location. Returns a destination Aws::S3::Key instance. # - # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<Aws::S3::Key:0xb7b1e240 ... > # puts key.name #=> 'logs/today/2.log' # key.exists? #=> true # def move_key(old_key_or_name, new_key_or_name) old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key) @@ -394,22 +394,22 @@ # 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 = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... > # key.exists? #=> true | false # key.put('Woohoo!') #=> true # key.exists? #=> true # def self.create(bucket, name, data=nil, meta_headers={}) new(bucket, name, data, {}, meta_headers) end # 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. + # Use Aws::S3::Key.create or bucket.key() instead. # 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 @@ -427,11 +427,11 @@ @meta_headers.merge!(meta_headers) end # Return key name as a String. # - # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # key = Aws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<Aws::S3::Key:0xb7b1e240 ... > # puts key #=> 'logs/today/1.log' # def to_s @name.to_s end @@ -474,11 +474,11 @@ # 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 = Aws::S3::Key.create(bucket, 'logs/today/1.log') # key.data = 'Qwerty' # key.put #=> true # ... # key.put('Olala!') #=> true # @@ -489,59 +489,59 @@ @bucket.s3.interface.put(@bucket.name, @name, @data, meta.merge(headers)) end # Rename an object. Returns new object name. # - # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... > + # 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 # def rename(new_name) @bucket.s3.interface.rename(@bucket.name, @name, new_name) @name = new_name end - # Create an object copy. Returns a destination RightAws::S3::Key instance. + # Create an object copy. Returns a destination Aws::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 = 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) #=> #<RightAws::S3::Key:0xb7b5e240 ... > + # key1.copy(key2) #=> #<Aws::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 = 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') #=> #<RightAws::S3::Key:0xb7b5e240 ... > + # new_key = key.copy('logs/today/888.log') #=> #<Aws::S3::Key:0xb7b5e240 ... > # key.exists? #=> true # new_key.exists? #=> true # 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 - # Move an object to other location. Returns a destination RightAws::S3::Key instance. + # Move an object to other location. Returns a destination Aws::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 = 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) #=> #<RightAws::S3::Key:0xb7b5e240 ... > + # key1.move(key2) #=> #<Aws::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 = 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') #=> #<RightAws::S3::Key:0xb7b5e240 ... > + # new_key = key.move('logs/today/888.log') #=> #<Aws::S3::Key:0xb7b5e240 ... > # key.exists? #=> false # new_key.exists? #=> true # 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) @@ -551,11 +551,11 @@ # 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 = 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"} @@ -609,11 +609,11 @@ end # 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 = Aws::S3::Key.create(bucket,'logs/today/1.log') # key.exists? #=> false # key.put('Woohoo!') #=> true # key.exists? #=> true # def exists? @@ -667,17 +667,17 @@ # # 2 . Use Grantee instances (the permission is a +String+ or an +Array+ of: 'READ', 'WRITE', # 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'): # # bucket = s3.bucket('my_awesome_bucket', true) - # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL, :apply) - # grantee2 = RightAws::S3::Grantee.new(bucket, 'xy3v3...5fhp', [READ, WRITE], :apply) + # grantee1 = Aws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL, :apply) + # grantee2 = Aws::S3::Grantee.new(bucket, 'xy3v3...5fhp', [READ, WRITE], :apply) # # There is only one way to get and to remove permission (via Grantee instances): # # grantees = bucket.grantees # a list of Grantees that have any access for this bucket - # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c') + # grantee1 = Aws::S3::Grantee.new(bucket, 'a123b...223c') # grantee1.perms #=> returns a list of perms for this grantee to that bucket # ... # grantee1.drop # remove all perms for this grantee # grantee2.revoke('WRITE') # revoke write access only # @@ -694,11 +694,11 @@ # Retrieve Owner information and a list of Grantee instances that have # a access to this thing (bucket or key). # # bucket = s3.bucket('my_awesome_bucket', true, 'public-read') # ... - # RightAws::S3::Grantee.owner_and_grantees(bucket) #=> [owner, grantees] + # Aws::S3::Grantee.owner_and_grantees(bucket) #=> [owner, grantees] # def self.owner_and_grantees(thing) if thing.is_a?(Bucket) bucket, key = thing, '' else @@ -716,11 +716,11 @@ # Retrieves a list of Grantees instances that have an access to this thing(bucket or key). # # bucket = s3.bucket('my_awesome_bucket', true, 'public-read') # ... - # RightAws::S3::Grantee.grantees(bucket) #=> grantees + # Aws::S3::Grantee.grantees(bucket) #=> grantees # def self.grantees(thing) owner_and_grantees(thing)[1] end @@ -748,14 +748,14 @@ # perms to +thing+ at S3. If +action+ == :apply_and_refresh then it performs. # both the actions. This is used for the new grantees that had no perms to # this thing before. The default action is :refresh. # # bucket = s3.bucket('my_awesome_bucket', true, 'public-read') - # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL) + # grantee1 = Aws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL) # ... - # grantee2 = RightAws::S3::Grantee.new(bucket, 'abcde...asdf', [FULL_CONTROL, READ], :apply) - # grantee3 = RightAws::S3::Grantee.new(bucket, 'aaaaa...aaaa', 'READ', :apply_and_refresh) + # grantee2 = Aws::S3::Grantee.new(bucket, 'abcde...asdf', [FULL_CONTROL, READ], :apply) + # grantee3 = Aws::S3::Grantee.new(bucket, 'aaaaa...aaaa', 'READ', :apply_and_refresh) # def initialize(thing, id, perms=[], action=:refresh, name=nil) @thing = thing @id = id @name = name @@ -886,38 +886,38 @@ end end - # RightAws::S3Generator and RightAws::S3Generator::Bucket methods: + # Aws::S3Generator and Aws::S3Generator::Bucket methods: # - # s3g = RightAws::S3Generator.new('1...2', 'nx...Y6') #=> #<RightAws::S3Generator:0xb7b5cc94> + # s3g = Aws::S3Generator.new('1...2', 'nx...Y6') #=> #<Aws::S3Generator:0xb7b5cc94> # # # List all buckets(method 'GET'): # buckets_list = s3g.buckets #=> 'https://s3.amazonaws.com:443/?Signature=Y...D&Expires=1180941864&AWSAccessKeyId=1...2' # # Create bucket link (method 'PUT'): - # bucket = s3g.bucket('my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8> + # bucket = s3g.bucket('my_awesome_bucket') #=> #<Aws::S3Generator::Bucket:0xb7bcbda8> # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2 # # ... or: - # bucket = RightAws::S3Generator::Bucket.create(s3g, 'my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8> + # bucket = Aws::S3Generator::Bucket.create(s3g, 'my_awesome_bucket') #=> #<Aws::S3Generator::Bucket:0xb7bcbda8> # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2 # # ... or: - # bucket = RightAws::S3Generator::Bucket.new(s3g, 'my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8> + # bucket = Aws::S3Generator::Bucket.new(s3g, 'my_awesome_bucket') #=> #<Aws::S3Generator::Bucket:0xb7bcbda8> # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2 # # List bucket(method 'GET'): # bucket.keys(1.day) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=i...D&Expires=1180942620&AWSAccessKeyId=1...2 # # Create/put key (method 'PUT'): # bucket.put('my_cool_key') #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=q...D&Expires=1180943094&AWSAccessKeyId=1...2 # # Get key data (method 'GET'): # bucket.get('logs/today/1.log', 1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=h...M%3D&Expires=1180820032&AWSAccessKeyId=1...2 # # Delete bucket (method 'DELETE'): # bucket.delete(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2 # - # RightAws::S3Generator::Key methods: + # Aws::S3Generator::Key methods: # # # Create Key instance: - # key = RightAws::S3Generator::Key.new(bicket, 'my_cool_key') #=> #<RightAws::S3Generator::Key:0xb7b7394c> + # key = Aws::S3Generator::Key.new(bicket, 'my_cool_key') #=> #<Aws::S3Generator::Key:0xb7b7394c> # # Put key data (method 'PUT'): # key.put #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=2...D&Expires=1180943302&AWSAccessKeyId=1...2 # # Get key data (method 'GET'): # key.get #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=a...D&Expires=1180820032&AWSAccessKeyId=1...2 # # Head key (method 'HEAD'): @@ -1002,10 +1002,10 @@ # Generates link to PUT key data. # # puts bucket.put('logs/today/1.log', 2.hour) # def put(key, meta_headers={}, expires=nil, headers={}) - meta = RightAws::S3::Key.add_meta_prefix(meta_headers) + meta = Aws::S3::Key.add_meta_prefix(meta_headers) @s3.interface.put_link(@name, key.to_s, nil, expires, meta.merge(headers)) end # Generate link to GET key data. #