Class: Net::Amazon::S3::Bucket

Inherits:
Object
  • Object
show all
Includes:
Comparable, Enumerable
Defined in:
lib/net/amazon/s3/bucket.rb

Overview

Represents an Amazon S3 bucket. This class should only be instantiated through one of the methods in the S3 class.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(s3, bucket_name, creation_date) ⇒ Bucket

Creates and returns a new Bucket object. You should never create new Bucket objects directly. Instead, use one of the methods in the S3 class.



17
18
19
20
21
22
23
 
# File 'lib/net/amazon/s3/bucket.rb', line 17

def initialize(s3, bucket_name, creation_date)
  @s3            = s3
  @name          = bucket_name
  @creation_date = creation_date

  @cache = {}
end

Instance Attribute Details

#creation_date ⇒ Object (readonly)

Returns the value of attribute creation_date.



13
14
15
 
# File 'lib/net/amazon/s3/bucket.rb', line 13

def creation_date
  @creation_date
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/net/amazon/s3/bucket.rb', line 13

def name
  @name
end

Instance Method Details

#<=>(bucket) ⇒ Object

Compares two buckets by name.



26
27
28
 
# File 'lib/net/amazon/s3/bucket.rb', line 26

def <=>(bucket)
  return @name <=> bucket.name
end

#create_object(object_key, value, metadata = {}) ⇒ Object Also known as: []=

Creates and returns a new S3::Object with the specified object_key and value. If this bucket already contains an object with the specified key, that object will be overwritten.

If value is an open IO stream, the value of the object will be read from the stream.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/net/amazon/s3/bucket.rb', line 36

def create_object(object_key, value, metadata = {})
  object_key_escaped = S3::Object.escape_key(object_key)
  
  headers = {}
  metadata.each {|key, value| headers["x-amz-meta-#{key}"] = value }
  
  response = @s3.request_put("/#{@name}/#{object_key_escaped}", value,
      headers)
  @s3.error?(response)

  @cache.delete(:objects)

  return get_object(object_key)
end

#delete_object(object_key) ⇒ Object

Deletes the specified object from this bucket.



54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/net/amazon/s3/bucket.rb', line 54

def delete_object(object_key)
  object_key_escaped = S3::Object.escape_key(object_key)

  unless object = get_object(object_key)
    raise S3Error::NoSuchKey, 'The specified key does not exist'
  end
  
  @cache.delete(:objects)
  
  return true unless @s3.error?(@s3.request_delete(
      "/#{@name}/#{object_key_escaped}"))
end

#each ⇒ Object

Iterates through the list of objects.



68
69
70
 
# File 'lib/net/amazon/s3/bucket.rb', line 68

def each
  get_objects.each {|key, value| yield key, value }
end

#get_object(object_key) ⇒ Object Also known as: []

Returns a S3::Object representing the specified object_key, or nil if the object doesn’t exist in this bucket.



74
75
76
 
# File 'lib/net/amazon/s3/bucket.rb', line 74

def get_object(object_key)
  return get_objects(object_key)[object_key]
end

#get_objects(prefix = '') ⇒ Object

Gets a list of all objects in this bucket whose keys begin with prefix. Returns a Hash of S3::Object objects indexed by object key.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/net/amazon/s3/bucket.rb', line 82

def get_objects(prefix = '')
  prefix = prefix.toutf8

  if @s3.options[:enable_cache] && !@cache[:objects].nil? &&
      !@cache[:objects][prefix].nil?
    return @cache[:objects][prefix]
  end
  
  if @cache[:objects].nil?
    @cache[:objects] = {}
  end
  
  objects      = {}
  request_uri  = "/#{@name}?prefix=#{URI.escape(prefix)}"
  is_truncated = true
  
  # The request is made in a loop because the S3 API limits results to pages
  # of 1,000 objects by default, so if there are more than 1,000 objects,
  # we'll have to send more requests to get them all.
  while is_truncated do
    response = @s3.request_get(request_uri)
    @s3.error?(response)
    
    xml = REXML::Document.new(response.body)
    
    if xml.root.elements['IsTruncated'].text == 'false'
      is_truncated = false
    else
      request_uri = "/#{@name}?prefix=#{URI.escape(prefix)}&marker=" +
          xml.root.elements.to_a('Contents').last.elements['Key'].text
    end
    
    next if xml.root.elements['Contents'].nil?
  
    xml.root.elements.each('Contents') do |element|
      object_key           = element.elements['Key'].text
      object_size          = element.elements['Size'].text
      object_etag          = element.elements['ETag'].text
      object_last_modified = Time.parse(
          element.elements['LastModified'].text)
      
      objects[object_key] = S3::Object.new(@s3, self, object_key,
          object_size, object_etag, object_last_modified)
    end
  end

  return @cache[:objects][prefix] = objects
end

#object_exist?(object_key) ⇒ Boolean Also known as: has_object?

Returns true if an object with the specified object_key exists in this bucket, false otherwise.

Returns:

  • (Boolean) 


133
134
135
 
# File 'lib/net/amazon/s3/bucket.rb', line 133

def object_exist?(object_key)
  return get_objects.has_key?(object_key)
end