view release on metacpan or  search on metacpan

lib/AWS/S3.pm  view on Meta::CPAN

has 'ua' => (
    is      => 'ro',
    isa     => 'LWP::UserAgent',
    default => sub { LWP::UserAgent::Determined->new }
);

has 'honor_leading_slashes' => (
    is      => 'ro',
    isa     => 'Bool',
    default => sub { 0 },
);

sub request {
    my ( $s, $type, %args ) = @_;

    my $class = "AWS::S3::Request::$type";

    load_class( $class );
    return $class->new( %args, s3 => $s, type => $type );
}    # end request()

sub owner {
    my $s = shift;

    my $type     = 'ListAllMyBuckets';
    my $request  = $s->request( $type );
    my $response = $request->request();

    # Linode/Akamai E3 endpoints do not include the `xmlns` in
    # ListAllMyBuckets, so use the localname to work with or
    # without a declared XML namespace.
    my $xml      = $response->xml;
    my ($node)   = $xml->getElementsByLocalName('Owner');
    return AWS::S3::Owner->new(
        id           => $node->getElementsByLocalName('ID')->string_value,
        display_name => $node->getElementsByLocalName('DisplayName')->string_value,
    );
}    # end owner()

sub buckets {
    my ( $s ) = @_;

    my $type     = 'ListAllMyBuckets';
    my $request  = $s->request( $type );
    my $response = $request->request();

    # Linode/Akamai E3 endpoints do not include the `xmlns` in
    # ListAllMyBuckets, so use the localname to work with or
    # without a declared XML namespace.
    my $xml     = $response->xml;
    my @buckets = ();
    foreach my $node ( $xml->getElementsByLocalName( 'Bucket' ) ) {
        push @buckets,
          AWS::S3::Bucket->new(
            name          => $node->getElementsByLocalName('Name')->string_value,
            creation_date => $node->getElementsByLocalName('CreationDate')->string_value,
            s3            => $s,
          );
    }    # end foreach()

    $LOG->debug('Listed AWS buckets', { buckets => [map $_->name, @buckets] });
    return @buckets;
}    # end buckets()

sub bucket {
    my ( $s, $name ) = @_;

    my ( $bucket ) = grep { $_->name eq $name } $s->buckets
      or return;
    $bucket;
}    # end bucket()

sub add_bucket {
    my ( $s, %args ) = @_;

    my $type     = 'CreateBucket';
    my $request  = $s->request(
        $type,
        bucket => $args{name},
        (
            $args{location} ? ( location => $args{location} )
                : $s->region ? ( location => $s->region )
                : ()
        ),
    );
    my $response = $request->request();

    if ( my $msg = $response->friendly_error() ) {
        die $msg;
    }    # end if()

    return $s->bucket( $args{name} );
}    # end add_bucket()

__PACKAGE__->meta->make_immutable;

__END__

=pod

=head1 NAME

AWS::S3 - Lightweight interface to Amazon S3 (Simple Storage Service)

=for html
<a href='https://travis-ci.org/leejo/AWS-S3?branch=master'><img src='https://travis-ci.org/leejo/AWS-S3.svg?branch=master' /></a>
<a href='https://coveralls.io/r/leejo/AWS-S3?branch=master'><img src='https://coveralls.io/repos/leejo/AWS-S3/badge.png?branch=master' alt='Coverage Status' /></a>

=head1 SYNOPSIS

  use AWS::S3;

  my $s3 = AWS::S3->new(
    access_key_id     => 'E654SAKIASDD64ERAF0O',
    secret_access_key => 'LgTZ25nCD+9LiCV6ujofudY1D6e2vfK0R4GLsI4H',
    session_token     => 'IQob3JpJZ2luXJ2VjJEL7//////////wE...',
    region            => 'eu-west-1', # set to relevant AWS region
    honor_leading_slashes => 0, # set to allow leading slashes in bucket names, defaults to 0
  );

  # Add a bucket:

lib/AWS/S3.pm  view on Meta::CPAN

Defaults to creating a new instance of L<LWP::UserAgent::Determined>

=head2 honor_leading_slashes

Optional. Boolean to set if bucket names should include any leading slashes
when sent to S3 - defaults to zero

=head1 PUBLIC PROPERTIES

=head2 access_key_id

String.  Read-only

=head2 secret_access_key

String.  Read-only.

=head2 secure

Boolean.  Read-only.

=head2 endpoint

String.  Read-only.

=head2 ua

L<LWP::UserAgent> object.  Read-only.

=head2 owner

L<AWS::S3::Owner> object.  Read-only.

=head1 PUBLIC METHODS

=head2 buckets

Returns an array of L<AWS::S3::Bucket> objects.

=head2 bucket( $name )

Returns the L<AWS::S3::Bucket> object matching C<$name> if found.

Returns nothing otherwise.

=head2 add_bucket( name => $name, location => 'us-west-1' )

Attempts to create a new bucket with the name provided. The location parameter is optional
and, as per the AWS docs, will default to "us-east-1".

On success, returns the new L<AWS::S3::Bucket>

On failure, dies with the error message.

See L<AWS::S3::Bucket> for details on how to use buckets (and access their files).

=head1 ENVIRONMENT VARIABLES

=head2 AWS_S3_DEBUG

If set, will print out debugging information to C<STDERR>.

=head1 SEE ALSO

L<The Amazon S3 API Documentation|http://docs.amazonwebservices.com/AmazonS3/latest/API/>

L<AWS::S3::Bucket>

L<AWS::S3::File>

L<AWS::S3::FileIterator>

L<AWS::S3::Owner>

=head1 AUTHOR

Originally John Drago C<jdrago_999@yahoo.com>, currently maintained by Lee Johnson (LEEJO) C<leejo@cpan.org>
with contributions from Evan Carroll, Robin Clarke, Ulrich Kautz, simbabque, Dave Rolsky

=head1 LICENSE

This software is Free software and may be used and redistributed under the same
terms as any version of perl itself.

Copyright John Drago 2011 all rights reserved.

=cut