Class: RightAws::S3::Bucket

Class

RightAws::S3::Bucket

In:

lib/s3/right_s3.rb

Parent:

Object

dot/m_13_0.png

Attributes

 creation_date
 name
 owner
 s3

Public Class methods

create(s3, name, create=false, perms=nil, headers={})

Create a Bucket instance. 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 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 = RightAws::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.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)

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

     # File lib/s3/right_s3.rb, line 131
131:       def self.create(s3, name, create=false, perms=nil, headers={}) 
132:         s3.bucket(name, create, perms, headers)
133:       end

new(s3, name, creation_date=nil, owner=nil)

Create a bucket instance. In normal use this method should not be called directly. Use RightAws::S3::Bucket.create or RightAws::S3.bucket instead.

     # File lib/s3/right_s3.rb, line 139
139:       def initialize(s3, name, creation_date=nil, owner=nil)
140:         @s3    = s3
141:         @name  = name
142:         @owner = owner
143:         @creation_date = creation_date
144:         if @creation_date && !@creation_date.is_a?(Time)
145:           @creation_date = Time.parse(@creation_date)
146:         end
147:       end

Public Instance methods

Remove all keys from a bucket. Returns true.

 bucket.clear #=> true

     # File lib/s3/right_s3.rb, line 330
330:       def clear
331:         @s3.interface.clear_bucket(@name)  
332:       end

copy_key(old_key_or_name, new_key_or_name)

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

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

     # File lib/s3/right_s3.rb, line 309
309:       def copy_key(old_key_or_name, new_key_or_name)
310:         old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
311:         old_key_or_name.copy(new_key_or_name)
312:       end

delete(force=false)

Delete a bucket. Bucket must be empty. If force is set, clears and deletes the bucket. Returns true.

 bucket.delete(true) #=> true

     # File lib/s3/right_s3.rb, line 351
351:       def delete(force=false)
352:         force ? @s3.interface.force_delete_bucket(@name) : @s3.interface.delete_bucket(@name)
353:       end

delete_folder(folder, separator='/')

Delete all keys where the ‘folder_key’ can be interpreted as a ‘folder’ name. Returns an array of string keys that have been deleted.

 bucket.keys.map{|key| key.name}.join(', ') #=> 'test, test/2/34, test/3, test1, test1/logs'
 bucket.delete_folder('test')               #=> ['test','test/2/34','test/3']

     # File lib/s3/right_s3.rb, line 341
341:       def delete_folder(folder, separator='/')
342:         @s3.interface.delete_folder(@name, folder, separator)
343:       end

disable_logging()

Disables S3 server access logging on a bucket. Takes no arguments.

     # File lib/s3/right_s3.rb, line 198
198:       def disable_logging
199:         xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"></BucketLoggingStatus>"
200:         @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc)
201:       end

enable_logging(params)

Enables S3 server access logging on a bucket. The target bucket must have been properly configured to receive server access logs.

 Params:
  :targetbucket - either the target bucket object or the name of the target bucket
  :targetprefix - the prefix under which all logs should be stored

 bucket.enable_logging(:targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/")
   => true

     # File lib/s3/right_s3.rb, line 190
190:       def enable_logging(params)
191:         AwsUtils.mandatory_arguments([:targetbucket, :targetprefix], params)
192:         AwsUtils.allow_only([:targetbucket, :targetprefix], params)
193:         xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"><LoggingEnabled><TargetBucket>#{params[:targetbucket]}</TargetBucket><TargetPrefix>#{params[:targetprefix]}</TargetPrefix></LoggingEnabled></BucketLoggingStatus>"
194:         @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc)
195:       end

full_name()

Alias for to_s

get(key, headers={})

Retrieve object data from Amazon. The key is a String or Key. Returns Key instance.

 key = bucket.get('logs/today/1.log') #=>
 puts key.data #=> 'sasfasfasdf'

     # File lib/s3/right_s3.rb, line 286
286:       def get(key, headers={})
287:         key = Key.create(self, key.to_s) unless key.is_a?(Key)
288:         key.get(headers)
289:       end

Return a list of grantees.

     # File lib/s3/right_s3.rb, line 357
357:       def grantees
358:         Grantee::grantees(self)
359:       end

key(key_name, head=false)

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 ... >
  # is the same as:
 key = RightAws::S3::Key.create(bucket, 'logs/today/1.log')
 key.head

     # File lib/s3/right_s3.rb, line 251
251:       def key(key_name, head=false)
252:         raise 'Key name can not be empty.' if key_name.blank?
253:         key_instance = nil
254:           # if this key exists - find it ....
255:         keys({'prefix'=>key_name}, head).each do |key|
256:           if key.name == key_name.to_s
257:             key_instance = key
258:             break
259:           end
260:         end
261:           # .... else this key is unknown
262:         unless key_instance
263:           key_instance = Key.create(self, key_name.to_s)
264:         end
265:         key_instance
266:       end

keys(options={}, head=false)

Retrieve a group of keys from Amazon. options is a hash: { ‘prefix’=>’’, ‘marker’=>’’, ‘max-keys’=>5, ‘delimiter’=>’’ }). Retrieves meta-headers information if head it true. Returns an array of Key instances.

 bucket.keys                     #=> # returns all keys from bucket
 bucket.keys('prefix' => 'logs') #=> # returns all keys that starts with 'logs'

     # File lib/s3/right_s3.rb, line 211
211:       def keys(options={}, head=false)
212:         keys_and_service(options, head)[0]
213:       end

keys_and_service(options={}, head=false)

Same as keys method but return an array of [keys, service_data]. where service_data is a hash with additional output information.

 keys, service = bucket.keys_and_service({'max-keys'=> 2, 'prefix' => 'logs'})
 p keys    #=> # 2 keys array
 p service #=> {"max-keys"=>"2", "prefix"=>"logs", "name"=>"my_awesome_bucket", "marker"=>"", "is_truncated"=>true}

     # File lib/s3/right_s3.rb, line 222
222:       def keys_and_service(options={}, head=false)
223:         opt = {}; options.each{ |key, value| opt[key.to_s] = value }
224:         service_data = {}
225:         thislist = {}
226:         list = []
227:         @s3.interface.incrementally_list_bucket(@name, opt) do |thislist|
228:           thislist[:contents].each do |entry|
229:             owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
230:             key = Key.new(self, entry[:key], nil, {}, {}, entry[:last_modified], entry[:e_tag], entry[:size], entry[:storage_class], owner)
231:             key.head if head
232:             list << key
233:           end
234:         end
235:         thislist.each_key do |key|
236:           service_data[key] = thislist[key] unless (key == :contents || key == :common_prefixes)
237:         end
238:         [list, service_data]
239:       end

Returns the bucket location

     # File lib/s3/right_s3.rb, line 169
169:       def location
170:         @location ||= @s3.interface.bucket_location(@name)
171:       end

Retrieves the logging configuration for a bucket. Returns a hash of {:enabled, :targetbucket, :targetprefix}

  bucket.logging_info()
  => {:enabled=>true, :targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/"}

     # File lib/s3/right_s3.rb, line 178
178:       def logging_info
179:         @s3.interface.get_logging_parse(:bucket => @name)
180:       end

move_key(old_key_or_name, new_key_or_name)

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

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

     # File lib/s3/right_s3.rb, line 320
320:       def move_key(old_key_or_name, new_key_or_name)
321:         old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
322:         old_key_or_name.move(new_key_or_name)
323:       end

Return a public link to bucket.

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

     # File lib/s3/right_s3.rb, line 163
163:       def public_link
164:         params = @s3.interface.params
165:         "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name}"
166:       end

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

Store object data. The key is a String or Key instance. Returns true.

 bucket.put('logs/today/1.log', 'Olala!') #=> true

     # File lib/s3/right_s3.rb, line 274
274:       def put(key, data=nil, meta_headers={}, perms=nil, headers={})
275:         key = Key.create(self, key.to_s, data, meta_headers) unless key.is_a?(Key) 
276:         key.put(data, perms, headers)
277:       end

rename_key(old_key_or_name, new_name)

Rename object. Returns RightAws::S3::Key instance.

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

     # File lib/s3/right_s3.rb, line 297
297:       def rename_key(old_key_or_name, new_name)
298:         old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
299:         old_key_or_name.rename(new_name)
300:         old_key_or_name
301:       end

Return bucket name as a String.

 bucket = RightAws::S3.bucket('my_awesome_bucket')
 puts bucket #=> 'my_awesome_bucket'

     # File lib/s3/right_s3.rb, line 154
154:       def to_s
155:         @name.to_s
156:       end