Class: CloudFiles::Container

Inherits:
Object
  • Object
show all
Defined in:
lib/cloudfiles/container.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(connection, name) ⇒ Container

Retrieves an existing CloudFiles::Container object tied to the current CloudFiles::Connection. If the requested container does not exist, it will raise a NoSuchContainerException.

Will likely not be called directly, instead use connection.container(‘container_name’) to retrieve the object.



31
32
33
34
35
36
37
38
39
 
# File 'lib/cloudfiles/container.rb', line 31

def initialize(connection,name)
  @connection = connection
  @name = name
  @storagehost = self.connection.storagehost
  @storagepath = self.connection.storagepath + "/" + URI.encode(@name).gsub(/&/,'%26')
  @cdnmgmthost = self.connection.cdnmgmthost
  @cdnmgmtpath = self.connection.cdnmgmtpath + "/" + URI.encode(@name).gsub(/&/,'%26')
  populate
end

Instance Attribute Details

#bytes ⇒ Object (readonly)

Size of the container (in bytes)



10
11
12
 
# File 'lib/cloudfiles/container.rb', line 10

def bytes
  @bytes
end

#cdn_enabled ⇒ Object (readonly)

True if container is public, false if container is private



16
17
18
 
# File 'lib/cloudfiles/container.rb', line 16

def cdn_enabled
  @cdn_enabled
end

#cdn_ttl ⇒ Object (readonly)

CDN container TTL (if container is public)



19
20
21
 
# File 'lib/cloudfiles/container.rb', line 19

def cdn_ttl
  @cdn_ttl
end

#cdn_url ⇒ Object (readonly)

CDN container URL (if container if public)



22
23
24
 
# File 'lib/cloudfiles/container.rb', line 22

def cdn_url
  @cdn_url
end

#connection ⇒ Object (readonly)

The parent CloudFiles::Connection object for this container



25
26
27
 
# File 'lib/cloudfiles/container.rb', line 25

def connection
  @connection
end

#count ⇒ Object (readonly)

Number of objects in the container



13
14
15
 
# File 'lib/cloudfiles/container.rb', line 13

def count
  @count
end

#name ⇒ Object (readonly)

Name of the container which corresponds to the instantiated container class



7
8
9
 
# File 'lib/cloudfiles/container.rb', line 7

def name
  @name
end

Instance Method Details

#create_object(objectname, make_path = false) ⇒ Object

Creates a new CloudFiles::StorageObject in the current container.

If an object with the specified name exists in the current container, that object will be returned. Otherwise, an empty new object will be returned.

Passing in the optional make_path argument as true will create zero-byte objects to simulate a filesystem path to the object, if an objectname with path separators (“/path/to/myfile.mp3”) is supplied. These path objects can be used in the Container.objects method.



195
196
197
 
# File 'lib/cloudfiles/container.rb', line 195

def create_object(objectname,make_path = false)
  CloudFiles::StorageObject.new(self,objectname,false,make_path)
end

#delete_object(objectname) ⇒ Object

Removes an CloudFiles::StorageObject from a container. True is returned if the removal is successful. Throws NoSuchObjectException if the object doesn’t exist. Throws InvalidResponseException if the request fails.

container.delete_object('new.txt')
=> true

container.delete_object('nonexistent_file.txt')
=> NoSuchObjectException: Object nonexistent_file.txt does not exist

Raises:



207
208
209
210
211
212
 
# File 'lib/cloudfiles/container.rb', line 207

def delete_object(objectname)
  response = self.connection.cfreq("DELETE",@storagehost,"#{@storagepath}/#{URI.encode(objectname).gsub(/&/,'%26')}")
  raise NoSuchObjectException, "Object #{objectname} does not exist" if (response.code == "404")
  raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "204")
  true
end

#empty? ⇒ Boolean

Returns true if a container is empty and returns false otherwise.

new_container.empty?
=> true

full_container.empty?
=> false

Returns:

  • (Boolean) 


171
172
173
 
# File 'lib/cloudfiles/container.rb', line 171

def empty?
  return (@count.to_i == 0)? true : false
end

#make_private ⇒ Object

Makes a container private and returns true upon success. Throws NoSuchContainerException if the container doesn’t exist or if the request fails.

Note that if the container was previously public, it will continue to exist out on the CDN until it expires.

container.make_private
=> true

Raises:



238
239
240
241
242
243
 
# File 'lib/cloudfiles/container.rb', line 238

def make_private
  headers = { "X-CDN-Enabled" => "False" }
  response = self.connection.cfreq("POST",@cdnmgmthost,@cdnmgmtpath,headers)
  raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")
  true
end

#make_public(ttl = 86400) ⇒ Object

Makes a container publicly available via the Cloud Files CDN and returns true upon success. Throws NoSuchContainerException if the container doesn’t exist or if the request fails.

Takes an optional argument, which is the CDN cache TTL in seconds (default 86400 seconds or 1 day, maximum 259200 or 3 days)

container.make_public(432000)
=> true

Raises:



221
222
223
224
225
226
227
228
229
 
# File 'lib/cloudfiles/container.rb', line 221

def make_public(ttl = 86400)
  response = self.connection.cfreq("PUT",@cdnmgmthost,@cdnmgmtpath)
  raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")

  headers = { "X-TTL" => ttl.to_s }
  response = self.connection.cfreq("POST",@cdnmgmthost,@cdnmgmtpath,headers)
  raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")
  true
end

#object(objectname) ⇒ Object Also known as: get_object

Returns the CloudFiles::StorageObject for the named object. Refer to the CloudFiles::StorageObject class for available methods. If the object exists, it will be returned. If the object does not exist, a NoSuchObjectException will be thrown.

object = container.object('test.txt')
object.data
=> "This is test data"

object = container.object('newfile.txt')
=> NoSuchObjectException: Object newfile.txt does not exist



80
81
82
83
 
# File 'lib/cloudfiles/container.rb', line 80

def object(objectname)
  o = CloudFiles::StorageObject.new(self,objectname,true)
  return o
end

#object_exists?(objectname) ⇒ Boolean

Returns true if object exists and returns false otherwise.

container.object_exists?('goodfile.txt')
=> true

container.object_exists?('badfile.txt')
=> false

Returns:

  • (Boolean) 


182
183
184
185
 
# File 'lib/cloudfiles/container.rb', line 182

def object_exists?(objectname)
  response = self.connection.cfreq("HEAD",@storagehost,"#{@storagepath}/#{URI.encode(objectname).gsub(/&/,'%26')}")
  return (response.code == "204")? true : false
end

#objects(params = {}) ⇒ Object Also known as: list_objects

Gathers a list of all available objects in the current container and returns an array of object names.

container = cf.container("My Container")
container.objects                     #=> [ "dog", "cat", "donkey", "monkeydir/capuchin"]

Pass a limit argument to limit the list to a number of objects:

container.objects(:limit => 1)                  #=> [ "dog" ]

Pass an offset with or without a limit to start the list at a certain object:

container.objects(:limit => 1, :offset => 2)                #=> [ "donkey" ]

Pass a prefix to search for objects that start with a certain string:

container.objects(:prefix => "do")       #=> [ "dog", "donkey" ]

Only search within a certain pseudo-filesystem path:

container.objects(:path => 'monkeydir')     #=> ["monkeydir/capuchin"]

All arguments to this method are optional.

Returns an empty array if no object exist in the container. Throws an InvalidResponseException if the request fails.

Raises:



102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/cloudfiles/container.rb', line 102

def objects(params = {})
  paramarr = []
  paramarr << ["limit=#{URI.encode(params[:limit].to_i).gsub(/&/,'%26')}"] if params[:limit]
  paramarr << ["offset=#{URI.encode(params[:offset].to_i).gsub(/&/,'%26')}"] if params[:offset]
  paramarr << ["prefix=#{URI.encode(params[:prefix]).gsub(/&/,'%26')}"] if params[:prefix]
  paramarr << ["path=#{URI.encode(params[:path]).gsub(/&/,'%26')}"] if params[:path]
  paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
  response = self.connection.cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}")
  return [] if (response.code == "204")
  raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
  return CloudFiles.lines(response.body)
end

#objects_detail(params = {}) ⇒ Object Also known as: list_objects_info

Retrieves a list of all objects in the current container along with their size in bytes, hash, and content_type. If no objects exist, an empty hash is returned. Throws an InvalidResponseException if the request fails. Takes a parameter hash as an argument, in the same form as the objects method.

Returns a hash in the same format as the containers_detail from the CloudFiles class.

container.objects_detail
=> {"test.txt"=>{:content_type=>"application/octet-stream", 
                 :hash=>"e2a6fcb4771aa3509f6b27b6a97da55b", 
                 :last_modified=>Mon Jan 19 10:43:36 -0600 2009, 
                 :bytes=>"16"}, 
    "new.txt"=>{:content_type=>"application/octet-stream", 
                :hash=>"0aa820d91aed05d2ef291d324e47bc96", 
                :last_modified=>Wed Jan 28 10:16:26 -0600 2009, 
                :bytes=>"22"}
   }

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/cloudfiles/container.rb', line 132

def objects_detail(params = {})
  paramarr = []
  paramarr << ["format=xml"]
  paramarr << ["limit=#{URI.encode(params[:limit].to_i).gsub(/&/,'%26')}"] if params[:limit]
  paramarr << ["offset=#{URI.encode(params[:offset].to_i).gsub(/&/,'%26')}"] if params[:offset]
  paramarr << ["prefix=#{URI.encode(params[:prefix]).gsub(/&/,'%26')}"] if params[:prefix]
  paramarr << ["path=#{URI.encode(params[:path]).gsub(/&/,'%26')}"] if params[:path]
  paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
  response = self.connection.cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}")
  return {} if (response.code == "204")
  raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
  doc = REXML::Document.new(response.body)
  detailhash = {}
  doc.elements.each("container/object") { |o|
    detailhash[o.elements["name"].text] = { :bytes => o.elements["bytes"].text, :hash => o.elements["hash"].text, :content_type => o.elements["content_type"].text, :last_modified => Time.parse(o.elements["last_modified"].text) }
  }
  doc = nil
  return detailhash
end

#populate ⇒ Object Also known as: refresh

Retrieves data about the container and populates class variables. It is automatically called when the Container class is instantiated. If you need to refresh the variables, such as size, count, cdn_enabled, cdn_ttl, and cdn_url, this method can be called again.

container.count
=> 2
[Upload new file to the container]
container.count
=> 2
container.populate
container.count
=> 3

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/cloudfiles/container.rb', line 53

def populate
  # Get the size and object count
  response = self.connection.cfreq("HEAD",@storagehost,@storagepath+"/")
  raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "204")
  @bytes = response["x-container-bytes-used"].to_i
  @count = response["x-container-object-count"].to_i

  # Get the CDN-related details
  response = self.connection.cfreq("HEAD",@cdnmgmthost,@cdnmgmtpath)
  raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "204")
  @cdn_enabled = ((response["x-cdn-enabled"] || "").downcase == "true") ? true : false
  @cdn_ttl = @cdn_enabled ? response["x-ttl"] : false
  @cdn_url = @cdn_enabled ? response["x-cdn-uri"] : false

  true
end

#public? ⇒ Boolean

Returns true if the container is public and CDN-enabled. Returns false otherwise.

public_container.public?
=> true

private_container.public?
=> false

Returns:

  • (Boolean) 


160
161
162
 
# File 'lib/cloudfiles/container.rb', line 160

def public?
  return @cdn_enabled
end

#to_s ⇒ Object

:nodoc:



245
246
247
 
# File 'lib/cloudfiles/container.rb', line 245

def to_s # :nodoc:
  @name
end