.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Amazon::S3::Bucket 3pm"
.TH Amazon::S3::Bucket 3pm "2018-08-17" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Amazon::S3::Bucket \- A container class for a S3 bucket and its contents.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Amazon::S3;
\&  
\&  # creates bucket object (no "bucket exists" check)
\&  my $bucket = $s3\->bucket("foo"); 
\&  
\&  # create resource with meta data (attributes)
\&  my $keyname = \*(Aqtesting.txt\*(Aq;
\&  my $value   = \*(AqT\*(Aq;
\&  $bucket\->add_key(
\&      $keyname, $value,
\&      {   content_type        => \*(Aqtext/plain\*(Aq,
\&          \*(Aqx\-amz\-meta\-colour\*(Aq => \*(Aqorange\*(Aq,
\&      }
\&  );
\&  
\&  # list keys in the bucket
\&  $response = $bucket\->list
\&      or die $s3\->err . ": " . $s3\->errstr;
\&  print $response\->{bucket}."\en";
\&  for my $key (@{ $response\->{keys} }) {
\&        print "\et".$key\->{key}."\en";  
\&  }
\&
\&  # check if resource exists.
\&  print "$keyname exists\en" if $bucket\->head_key($keyname);
\&
\&  # delete key from bucket
\&  $bucket\->delete_key($keyname);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Instaniates a new bucket object.
.PP
Requires a hash containing two arguments:
.IP "bucket" 4
.IX Item "bucket"
The name (identifier) of the bucket.
.IP "account" 4
.IX Item "account"
The S3::Amazon object (representing the S3 account) this
bucket is associated with.
.PP
\&\s-1NOTE:\s0 This method does not check if a bucket actually
exists. It simply instaniates the bucket.
.PP
Typically a developer will not call this method directly,
but work through the interface in S3::Amazon that will
handle their creation.
.SS "add_key"
.IX Subsection "add_key"
Takes three positional parameters:
.IP "key" 4
.IX Item "key"
A string identifier for the resource in this bucket
.IP "value" 4
.IX Item "value"
A \s-1SCALAR\s0 string representing the contents of the resource.
.IP "configuration" 4
.IX Item "configuration"
A \s-1HASHREF\s0 of configuration data for this key. The configuration
is generally the \s-1HTTP\s0 headers you want to pass the S3
service. The client library will add all necessary headers.
Adding them to the configuration hash will override what the
library would send and add headers that are not typically
required for S3 interactions.
.Sp
In addition to additional and overridden \s-1HTTP\s0 headers, this
\&\s-1HASHREF\s0 can have a \f(CW\*(C`acl_short\*(C'\fR key to set the permissions
(access) of the resource without a separate call via
\&\f(CW\*(C`add_acl\*(C'\fR or in the form of an \s-1XML\s0 document.  See the
documentation in \f(CW\*(C`add_acl\*(C'\fR for the values and usage.
.PP
Returns a boolean indicating its success. Check \f(CW\*(C`err\*(C'\fR and
\&\f(CW\*(C`errstr\*(C'\fR for error message if this operation fails.
.SS "add_key_filename"
.IX Subsection "add_key_filename"
The method works like \f(CW\*(C`add_key\*(C'\fR except the value is assumed
to be a filename on the local file system. The file will 
be streamed rather then loaded into memory in one big chunk.
.ie n .SS "head_key $key_name"
.el .SS "head_key \f(CW$key_name\fP"
.IX Subsection "head_key $key_name"
Returns a configuration \s-1HASH\s0 of the given key. If a key does
not exist in the bucket \f(CW\*(C`undef\*(C'\fR will be returned.
.ie n .SS "get_key $key_name, [$method]"
.el .SS "get_key \f(CW$key_name\fP, [$method]"
.IX Subsection "get_key $key_name, [$method]"
Takes a key and an optional \s-1HTTP\s0 method and fetches it from
S3. The default \s-1HTTP\s0 method is \s-1GET.\s0
.PP
The method returns \f(CW\*(C`undef\*(C'\fR if the key does not exist in the
bucket and throws an exception (dies) on server errors.
.PP
On success, the method returns a \s-1HASHREF\s0 containing:
.IP "content_type" 4
.IX Item "content_type"
.PD 0
.IP "etag" 4
.IX Item "etag"
.IP "value" 4
.IX Item "value"
.ie n .IP "@meta" 4
.el .IP "\f(CW@meta\fR" 4
.IX Item "@meta"
.PD
.ie n .SS "get_key_filename $key_name, $method, $filename"
.el .SS "get_key_filename \f(CW$key_name\fP, \f(CW$method\fP, \f(CW$filename\fP"
.IX Subsection "get_key_filename $key_name, $method, $filename"
This method works like \f(CW\*(C`get_key\*(C'\fR, but takes an added
filename that the S3 resource will be written to.
.ie n .SS "delete_key $key_name"
.el .SS "delete_key \f(CW$key_name\fP"
.IX Subsection "delete_key $key_name"
Permanently removes \f(CW$key_name\fR from the bucket. Returns a
boolean value indicating the operations success.
.SS "delete_bucket"
.IX Subsection "delete_bucket"
Permanently removes the bucket from the server. A bucket
cannot be removed if it contains any keys (contents).
.PP
This is an alias for \f(CW\*(C`$s3\-\*(C'\fRdelete_bucket($bucket)>.
.SS "list"
.IX Subsection "list"
List all keys in this bucket.
.PP
See \*(L"list_bucket\*(R" in Amazon::S3 for documentation of this
method.
.SS "list_all"
.IX Subsection "list_all"
List all keys in this bucket without having to worry about
\&'marker'. This may make multiple requests to S3 under the
hood.
.PP
See \*(L"list_bucket_all\*(R" in Amazon::S3 for documentation of this
method.
.SS "get_acl"
.IX Subsection "get_acl"
Retrieves the Access Control List (\s-1ACL\s0) for the bucket or
resource as an \s-1XML\s0 document.
.IP "key" 4
.IX Item "key"
The key of the stored resource to fetch. This parameter is
optional. By default the method returns the \s-1ACL\s0 for the
bucket itself.
.ie n .SS "set_acl $conf"
.el .SS "set_acl \f(CW$conf\fP"
.IX Subsection "set_acl $conf"
Retrieves the Access Control List (\s-1ACL\s0) for the bucket or
resource. Requires a \s-1HASHREF\s0 argument with one of the following keys:
.IP "acl_xml" 4
.IX Item "acl_xml"
An \s-1XML\s0 string which contains access control information
which matches Amazon's published schema.
.IP "acl_short" 4
.IX Item "acl_short"
Alternative shorthand notation for common types of ACLs that
can be used in place of a \s-1ACL XML\s0 document.
.Sp
According to the Amazon S3 \s-1API\s0 documentation the following recognized acl_short
types are defined as follows:
.RS 4
.IP "private" 4
.IX Item "private"
Owner gets \s-1FULL_CONTROL.\s0 No one else has any access rights.
This is the default.
.IP "public-read" 4
.IX Item "public-read"
Owner gets \s-1FULL_CONTROL\s0 and the anonymous principal is
granted \s-1READ\s0 access. If this policy is used on an object, it
can be read from a browser with no authentication.
.IP "public-read-write" 4
.IX Item "public-read-write"
Owner gets \s-1FULL_CONTROL,\s0 the anonymous principal is granted
\&\s-1READ\s0 and \s-1WRITE\s0 access. This is a useful policy to apply to a
bucket, if you intend for any anonymous user to \s-1PUT\s0 objects
into the bucket.
.IP "authenticated-read" 4
.IX Item "authenticated-read"
Owner gets \s-1FULL_CONTROL,\s0 and any principal authenticated as
a registered Amazon S3 user is granted \s-1READ\s0 access.
.RE
.RS 4
.RE
.IP "key" 4
.IX Item "key"
The key name to apply the permissions. If the key is not
provided the bucket \s-1ACL\s0 will be set.
.PP
Returns a boolean indicating the operations success.
.SS "get_location_constraint"
.IX Subsection "get_location_constraint"
Returns the location constraint data on a bucket.
.PP
For more information on location constraints, refer to the
Amazon S3 Developer Guide.
.SS "err"
.IX Subsection "err"
The S3 error code for the last error the account encountered.
.SS "errstr"
.IX Subsection "errstr"
A human readable error string for the last error the account encountered.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Amazon::S3
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Please see the Amazon::S3 manpage for author, copyright, and
license information.