NAME

Net::Mosso::CloudFiles::Object - Represent a Cloud Files object

SYNOPSIS

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

  # 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 download an object to a local file
  $yyy->get_filename('README.downloaded');

DESCRIPTION

This class represents an object in Cloud Files. It is created by calling object or objects on a Net::Mosso::CloudFiles::Container object.

METHODS

name

Returns the name of the object.

  say 'has name ' . $object->name;

head

Fetches the metadata of the object:

  $object->head;

When set to true, forces md5 calculation on every file download and compares it to the provided etag. This can be a very expensive operation, especially on larger files. Setting always_check_etag to false will avoid the checksum on the file and will validate the file transfer was complete by comparing the file sizes after download. Defaults to true.

cache_value

When set to true, any values retrieved from the server will be cached within the object, this allows you to continue to use the value without re-retrieving it from CloudFiles repeatedly. Defaults to false.

get

Fetches the metadata and content of an object:

  my $value = $object->get;

If cache_value is enabled, will not re-retrieve the value from CloudFiles. To force re-retrieval, pass true to the get routine:

  my $value = $object->get(1);

get_filename

Downloads the content of an object to a local file, checks the integrity of the file, sets metadata in the object and sets the last modified time of the file to the same as the object.

  $object->get_filename('README.downloaded');

If cache_value is enabled and the file has already been retrieved and is present on the filesystem with the filename provided, and the file size and md5 hash of the local file match what is in CloudFiles, the file will not be re-retrieved and the local file will be returned as-is. To force a re-fetch of the file, pass a true value as the second arg to get_filename():

  $object->get_filename('README.downloaded',1);

delete

Deletes an object:

  $object->delete;

put

Creates a new object:

  my $xxx = $container->object( name => 'XXX' );
  $xxx->put('this is the value');

put_filename

Creates a new object with the contents of a local file:

  my $yyy = $container->object( name => 'YYY', content_type => 'text/plain' );
  $yyy->put_filename('README');

etag

Returns the entity tag of the object, which is its MD5:

  say 'has md5 ' . $object->etag;

size

Return the size of an object in bytes:

  say 'has size ' . $object->size;

content_type

Return the content type of an object:

  say 'has content type ' . $object->content_type;

last_modified

Return the last modified time of an object as a DateTime object:

  say 'has last_modified ' . $object->last_modified;

object_metadata

Sets or returns a hashref of metadata to be stored along with the file in CloudFiles. This hashref must containe key => value pairs and values must be scalar type, if you require storage of complex data, you will need to flatten it in some way prior to setting it here. Also, due to the way that CloudFiles works with metadata, when retrieved from CloudFiles, your keys will be lowercase. Note that since underscores are not permitted in keys within CloudFiles, any underscores are translated to dashes when transmitted to CloudFiles. They are re-translated when they are retrieved. This is mentioned only because if you access your data through a different language or interface, your metadata keys will contain dashes instead of underscores.

AUTHOR

Leon Brocard <acme@astray.com>.

COPYRIGHT

LICENSE

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