/ 
WebService-Rackspace-CloudFiles-2.03
River stage one • 1 direct dependent • 1 total dependent
/ WebService::Rackspace::CloudFiles

NAME

WebService::Rackspace::CloudFiles - Interface to Rackspace CloudFiles service

SYNOPSIS

  use WebService::Rackspace::CloudFiles;
  use Perl6::Say;

  my $cloudfiles = WebService::Rackspace::CloudFiles->new(
      user => 'myusername',
      key  => 'mysecretkey',
  );

  # list all containers
  my @containers = $cloudfiles->containers;
  foreach my $container (@containers) {
      say 'have container ' . $container->name;
  }

  # create a new container
  my $container = $cloudfiles->create_container(name => 'testing');

  # use an existing container
  my $existing_container = $cloudfiles->container(name => 'testing');

  my $total_bytes_used = $cloudfiles->total_bytes_used;
  say "used $total_bytes_used";

  my $object_count = $container->object_count;
  say "$object_count objects";

  my $bytes_used = $container->bytes_used;
  say "$bytes_used bytes";

  # returns a Data::Stream::Bulk object
  # as it may have to make multiple HTTP requests
  my @objects = $container->objects->all;
  foreach my $object (@objects) {
      say 'have object ' . $object->name;
      # also size, etag, content_type, last_modified
  }
  my @objects2 = $container->objects(prefix => 'dir/')->all;

  # To create a new object
  my $xxx = $container->object( name => 'XXX' );
  $xxx->put('this is the value');

  # To set metadata of an object:
  $xxx->object_metadata({
	  description => 'this is a description',
	  useful_number => 17
  });
  
  # To create a new object with the contents of a local file
  my $yyy = $container->object( name => 'YYY', content_type => 'text/plain' );
  $yyy->put_filename('README');

  # To fetch an object:
  my $xxx2 = $container->object( name => 'XXX' );
  my $value = $xxx2->get;
  say 'has name ' . $xxx2->name;
  say 'has md5 ' . $xxx2->etag;
  say 'has size ' . $xxx2->size;
  say 'has content type ' . $xxx2->content_type;
  say 'has last_modified ' . $xxx2->last_modified;

  # To fetch metadata of an object:
  say 'metadata description ' . $xxx2->object_metadata->{'description'};
  say 'metadata useful_number ' . $xxx2->object_metadata->{'useful_number'};
  
  # To download an object to a local file
  $yyy->get_filename('README.downloaded');

  $object->delete;

  $container->delete;

DESCRIPTION

This module was forked from Net::Mosso::CloudFiles which was written by Leon Brocard <acme@astray.com>. However, due to Mosso changing its name to Rackspace it felt right to fork the module to a new namespace. Upgrading from Net::Mosso::CloudFiles 0.44 should only require you to rename all Net::Mosso entries to WebService::Rackspace.

This module provides a simple interface to the Rackspace Cloud Files service. "Cloud Files is reliable, scalable and affordable web-based storage for backing up and archiving all your static content". Find out more at http://www.rackspacecloud.com/cloud_hosting_products/files.

To use this module you will need to sign up to Rackspace Cloud Files and provide a "user" and "key". If you use this module, you will incurr costs as specified by Rackspace. Please check the costs. If you use this module with your user and key you will be responsible for these costs.

I highly recommend reading all about Cloud Files, but in a nutshell data is stored in objects. Objects are referenced by names and objects are stored in containers.

METHODS

new

The constructor logs you into Cloud Files:

my $cloudfiles = WebService::Rackspace::CloudFiles->new(
    user => 'myusername',
    key  => 'mysecretkey',
);

A location for the Cloud Files can now be specified. Valid locations are currently usa and uk, the default location is usa

my $cloudfiles = WebService::Rackspace::CloudFiles->new(
    user => 'myusername',
    key  => 'mysecretkey',
    location  => 'uk',
);

If you wish to use a custom location url instead, location_url can be used to override the usual sites:

my $cloudfiles = WebService::Rackspace::CloudFiles->new(
    user => 'myusername',
    key  => 'mysecretkey',
    location_url  => 'https://my.cloudfile.me/v1.0',
);

containers

List all the containers and return them as WebService::Rackspace::CloudFiles::Container objects:

my @containers = $cloudfiles->containers;

create_container

Create a new container and return it as a WebService::Rackspace::CloudFiles::Container object:

my $container = $cloudfiles->create_container(name => 'testing');

container

Use an existing container and return it as a WebService::Rackspace::CloudFiles::Container object:

my $existing_container = $cloudfiles->container(name => 'testing');

total_bytes_used

Returns the total amount of bytes used in your Cloud Files account:

my $total_bytes_used = $cloudfiles->total_bytes_used;

connection_cache_class

iterator_callback_class

key

location

locations

retries

timeout

user

TESTING

Testing CloudFiles is a tricky thing. Rackspace charges you a bit of money each time you use their service. And yes, testing counts as using. Because of this, this module's test suite skips testing unless you set the following three environment variables, along the lines of:

CLOUDFILES_EXPENSIVE_TESTS=1 CLOUDFILES_USER=username CLOUDFILES_KEY=15bf43... perl t/simple.t

SEE ALSO

WebService::Rackspace::CloudFiles::Container, WebService::Rackspace::CloudFiles::Object.

AUTHORS

Christiaan Kras <ckras@cpan.org>. Net::Mosso::CloudFiles by Leon Brocard <acme@astray.com>.

COPYRIGHT

Copyright (C) 2010-2011, Christiaan Kras Copyright (C) 2008-9, Leon Brocard

LICENSE

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.