Class: S33r::NamedBucket

Inherits:
Client
  • Object
show all
Defined in:
lib/s33r/named_bucket.rb

Overview

Wraps the S33r::Client class to make it more convenient for use with a single bucket.

Constant Summary

Constants included from S33r

AWS_AUTH_HEADER_VALUE, AWS_HEADER_PREFIX, BUCKET_LIST_MAX_MAX_KEYS, CANNED_ACLS, DEFAULT_CHUNK_SIZE, DEFAULT_EXPIRY_SECS, GRANTEE_TYPES, GROUP_ACL_URI_BASE, HOST, INTERESTING_HEADERS, METADATA_PREFIX, METHOD_VERBS, NAMESPACE, NAMESPACE_URI, NON_SSL_PORT, PERMISSIONS, PORT, REQUIRED_HEADERS, RESPONSE_NAMESPACE_URI, S3_GROUP_TYPES

Instance Attribute Summary collapse

Attributes inherited from Client

#aws_access_key, #aws_secret_access_key, #chunk_size, #client_headers, #log_bucket, #use_ssl

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Client

#add_client_headers, #bucket_exists?, #create_bucket, #delete_bucket, #disable_log_target, #disable_logging, #do_delete, #do_get, #do_head, #do_post, #do_put, #do_request, #enable_log_target, #enable_logging, #get_acl, #get_client, #get_logging, #get_object, #get_requester, #get_resource, #list, #list_bucket, #list_buckets, load_config, #make_private, #make_public, #put_resource, #resource_exists?, #set_acl, #set_logging

Methods included from S33r

#add_default_headers, #bucket_name_valid?, #canned_acl_header, #generate_auth_header_value, #generate_canonical_string, #generate_querystring, #generate_signature, #guess_mime_type, keys_to_symbols, #metadata_headers, parse_expiry, remove_namespace, #s3_acl_path, #s3_logging_path, #s3_path, #s3_public_url, #s3_url

Constructor Details

#initialize(aws_access_key, aws_secret_access_key, options = {}) {|_self| ... } ⇒ NamedBucket

Initialize a NamedBucket instance.

options is a hash of options for this instance:

  • :default_bucket => 'xxxx': name of the bucket this client is attached to.

  • :public_contents => true: all items put into bucket are made public (can be overridden per request).

  • :strict => true: check whether the bucket exists before attempting to initialize; initialization \

fails if the bucket does not exist

Yields:

  • (_self)

Yield Parameters:



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/s33r/named_bucket.rb', line 27

def initialize(aws_access_key, aws_secret_access_key, options={}, &block)    
  super(aws_access_key, aws_secret_access_key, options)
  
  @name = options[:default_bucket]
  if @name.nil?
    raise S33rException::MissingBucketName, "NamedBucket cannot be initialised without specifying\
    a :default_bucket option"
  end

  # holds a BucketListing instance
  @listing = nil

  # all content should be created as public-read
  @public_contents = (true == options[:public_contents])
  @client_headers.merge!(canned_acl_header('public-read')) if @public_contents
  
  @strict = (true == options[:strict])
  if @strict && !bucket_exists?(@name)
    raise S33rException::MissingResource, "Non-existent bucket #{@bucket_name} specified"
  end
  
  yield self if block_given?
end

Instance Attribute Details

#dump_requests ⇒ Object

Returns the value of attribute dump_requests.



9
10
11
 
# File 'lib/s33r/named_bucket.rb', line 9

def dump_requests
  @dump_requests
end

#name ⇒ Object

Returns the value of attribute name.



9
10
11
 
# File 'lib/s33r/named_bucket.rb', line 9

def name
  @name
end

#public_contents ⇒ Object

Returns the value of attribute public_contents.



9
10
11
 
# File 'lib/s33r/named_bucket.rb', line 9

def public_contents
  @public_contents
end

#strict ⇒ Object

Returns the value of attribute strict.



9
10
11
 
# File 'lib/s33r/named_bucket.rb', line 9

def strict
  @strict
end

Class Method Details

.init(config_file) ⇒ Object

Initialize an instance from a config_file. The config. file can include a separate options section specifying options specific to NamedBucket instances (see the initialize method for more details). Other options are as for S33r::Client.init.



15
16
17
18
 
# File 'lib/s33r/named_bucket.rb', line 15

def NamedBucket.init(config_file)
  aws_access_key, aws_secret_access_key, options = super.class.load_config(config_file)
  NamedBucket.new(aws_access_key, aws_secret_access_key, options)
end

Instance Method Details

#[](key) ⇒ Object

Get a single object from a bucket as a blob.



62
63
64
 
# File 'lib/s33r/named_bucket.rb', line 62

def [](key)
  get_resource(@name, key).body
end

#delete_resource(resource_key, headers = {}) ⇒ Object

Delete an object from the bucket. NB S3 doesn’t discriminate between successfully deleting a key and trying to delete a non-existent key (both return a 204). If you want to test for existence first, use key_exists?.



117
118
119
120
 
# File 'lib/s33r/named_bucket.rb', line 117

def delete_resource(resource_key, headers={})
  super(@name, resource_key, headers)
  listing
end

#destroy(headers = {}, options = {}) ⇒ Object

Delete the bucket.



78
79
80
 
# File 'lib/s33r/named_bucket.rb', line 78

def destroy(headers={}, options={})
  delete_bucket(@name, headers, options)
end

#each_item ⇒ Object

List content of the bucket, and attach each item to this bucket as it is yielded.



88
89
90
 
# File 'lib/s33r/named_bucket.rb', line 88

def each_item
  listing.contents.each_value { |item| item.named_bucket = self; yield item }
end

#exists? ⇒ Boolean

Does this bucket exist? Returns true if the bucket this NamedBucket is mapped to exists.

Returns:

  • (Boolean) 


73
74
75
 
# File 'lib/s33r/named_bucket.rb', line 73

def exists?
  bucket_exists?(@name)
end

#key_exists?(key) ⇒ Boolean

Does the given key exist in the bucket? Returns boolean

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/s33r/named_bucket.rb', line 94

def key_exists?(key)
  resource_exists?(@name, key)
end

#keys ⇒ Object

Get a pretty list of the keys in the bucket.



83
84
85
 
# File 'lib/s33r/named_bucket.rb', line 83

def keys
  listing.pretty
end

#listing ⇒ Object

Get a BucketListing instance for the content of this bucket.



67
68
69
 
# File 'lib/s33r/named_bucket.rb', line 67

def listing
  list_bucket(@name)
end

#public_contents? ⇒ Boolean

Are all objects added to this bucket made public by default?

Returns:

  • (Boolean) 


52
53
54
 
# File 'lib/s33r/named_bucket.rb', line 52

def public_contents?
  @public_contents
end

#put_file(filename, resource_key = nil, headers = {}, options = {}) ⇒ Object

Put a file into the bucket.



104
105
106
 
# File 'lib/s33r/named_bucket.rb', line 104

def put_file(filename, resource_key=nil, headers={}, options={})
  super(filename, @name, resource_key, headers, options)
end

#put_stream(data, resource_key, headers = {}) ⇒ Object

Put a generic stream (e.g. from a file handle) into the bucket.



109
110
111
 
# File 'lib/s33r/named_bucket.rb', line 109

def put_stream(data, resource_key, headers={})
  put_resource(@name, resource_key, data, headers)
end

#put_text(string, resource_key, headers = {}) ⇒ Object

Put a string into a key inside the bucket.



99
100
101
 
# File 'lib/s33r/named_bucket.rb', line 99

def put_text(string, resource_key, headers={})
  super(string, @name, resource_key, headers)
end

#s3_authenticated_url(resource_key, expires = (Time.now.to_i + DEFAULT_EXPIRY_SECS)) ⇒ Object

Generate an authenticated URL (see docs.amazonwebservices.com/AmazonS3/2006-03-01/) for an object inside this bucket.

expires: time in secs since the epoch when the link should become invalid.



126
127
128
 
# File 'lib/s33r/named_bucket.rb', line 126

def s3_authenticated_url(resource_key, expires=(Time.now.to_i + DEFAULT_EXPIRY_SECS))
  super(@aws_access_key, @aws_secret_access_key, @name, resource_key, expires)
end

#strict? ⇒ Boolean

Is this a strict bucket (i.e. the target bucket must exist on S3)?

Returns:

  • (Boolean) 


57
58
59
 
# File 'lib/s33r/named_bucket.rb', line 57

def strict?
  @strict
end