Provided by: libnet-amazon-s3-perl_0.59-1_all bug

NAME

       Net::Amazon::S3::Bucket - convenience object for working with Amazon S3 buckets

VERSION

       version 0.59

SYNOPSIS

         use Net::Amazon::S3;

         my $bucket = $s3->bucket("foo");

         ok($bucket->add_key("key", "data"));
         ok($bucket->add_key("key", "data", {
            content_type => "text/html",
           'x-amz-meta-colour' => 'orange',
         }));

         # the err and errstr methods just proxy up to the Net::Amazon::S3's
         # objects err/errstr methods.
         $bucket->add_key("bar", "baz") or
             die $bucket->err . $bucket->errstr;

         # fetch a key
         $val = $bucket->get_key("key");
         is( $val->{value},               'data' );
         is( $val->{content_type},        'text/html' );
         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
         is( $val->{'x-amz-meta-colour'}, 'orange' );

         # returns undef on missing or on error (check $bucket->err)
         is(undef, $bucket->get_key("non-existing-key"));
         die $bucket->errstr if $bucket->err;

         # fetch a key's metadata
         $val = $bucket->head_key("key");
         is( $val->{value},               '' );
         is( $val->{content_type},        'text/html' );
         is( $val->{etag},                'b9ece18c950afbfa6b0fdbfa4ff731d3' );
         is( $val->{'x-amz-meta-colour'}, 'orange' );

         # delete a key
         ok($bucket->delete_key($key_name));
         ok(! $bucket->delete_key("non-exist-key"));

         # delete the entire bucket (Amazon requires it first be empty)
         $bucket->delete_bucket;

DESCRIPTION

       This module represents an S3 bucket.  You get a bucket object from the Net::Amazon::S3
       object.

METHODS

   new
       Create a new bucket object. Expects a hash containing these two arguments:

       bucket
       account

   add_key
       Takes three positional parameters:

       key
       value
       configuration
           A hash of configuration data for this key. (See synopsis);

       Returns a boolean.

   add_key_filename
       Use this to upload a large file to S3. Takes three positional parameters:

       key
       filename
       configuration
           A hash of configuration data for this key. (See synopsis);

       Returns a boolean.

   copy_key
       Creates (or replaces) a key, copying its contents from another key elsewhere in S3.  Takes
       the following parameters:

       key The key to (over)write

       source
           Where to copy the key from. Should be in the form "/bucketname/keyname"/.

       conf
           Optional configuration hash. If present and defined, the configuration (ACL and
           headers) there will be used for the new key; otherwise it will be copied from the
           source key.

   edit_metadata
       Changes the metadata associated with an existing key. Arguments:

       key The key to edit

       conf
           The new configuration hash to use

   head_key KEY
       Takes the name of a key in this bucket and returns its configuration hash

   get_key $key_name [$method]
       Takes a key name and an optional HTTP method (which defaults to "GET".  Fetches the key
       from AWS.

       On failure:

       Returns undef on missing content, throws an exception (dies) on server errors.

       On success:

       Returns a hashref of { content_type, etag, value, @meta } on success. Other values from
       the server are there too, with the key being lowercased.

   get_key_filename $key_name $method $filename
       Use this to download large files from S3. Takes a key name and an optional HTTP method
       (which defaults to "GET". Fetches the key from AWS and writes it to the filename. THe
       value returned will be empty.

       On failure:

       Returns undef on missing content, throws an exception (dies) on server errors.

       On success:

       Returns a hashref of { content_type, etag, value, @meta } on success

   delete_key $key_name
       Removes $key from the bucket. Forever. It's gone after this.

       Returns true on success and false on failure

   delete_bucket
       Delete the current bucket object from the server. Takes no arguments.

       Fails if the bucket has anything in it.

       This is an alias for "$s3->delete_bucket($bucket)"

   list
       List all keys in this bucket.

       see "list_bucket" in Net::Amazon::S3 for documentation of this method.

   list_all
       List all keys in this bucket without having to worry about 'marker'. This may make
       multiple requests to S3 under the hood.

       see "list_bucket_all" in Net::Amazon::S3 for documentation of this method.

   get_acl
       Takes one optional positional parameter

       key (optional)
           If no key is specified, it returns the acl for the bucket.

       Returns an acl in XML format.

   set_acl
       Takes a configuration hash_ref containing:

       acl_xml (cannot be used in conjunction with acl_short)
           An XML string which contains access control information which matches Amazon's
           published schema.  There is an example of one of these XML strings in the tests for
           this module.

       acl_short (cannot be used in conjunction with acl_xml)
           You can use the shorthand notation instead of specifying XML for certain 'canned'
           types of acls.

           (from the Amazon API documentation)

           private: Owner gets FULL_CONTROL. No one else has any access rights.  This is the
           default.

           public-read:Owner gets FULL_CONTROL and the anonymous principal is granted READ
           access. If this policy is used on an object, it can be read from a browser with no
           authentication.

           public-read-write:Owner gets FULL_CONTROL, the anonymous principal is granted READ and
           WRITE access. This is a useful policy to apply to a bucket, if you intend for any
           anonymous user to PUT objects into the bucket.

           authenticated-read:Owner gets FULL_CONTROL, and any principal authenticated as a
           registered Amazon S3 user is granted READ access.

       key (optional)
           If the key is not set, it will apply the acl to the bucket.

       Returns a boolean.

   get_location_constraint
       Retrieves the location constraint set when the bucket was created. Returns a string (eg,
       'EU'), or undef if no location constraint was set.

   err
       The S3 error code for the last error the object ran into

   errstr
       A human readable error string for the last error the object ran into

SEE ALSO

       Net::Amazon::S3

AUTHOR

       Pedro Figueiredo <me@pedrofigueiredo.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Amazon Digital Services, Leon Brocard, Brad
       Fitzpatrick, Pedro Figueiredo.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.