The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Coro-Amazon-SimpleDB-0.04
River stage one • 1 direct dependent • 1 total dependent
++
/ Coro::Amazon::SimpleDB

NAME

Coro::Amazon::SimpleDB - Use Amazon::SimpleDB::Client to do asynchronous requests

VERSION

Version 0.01

SYNOPSIS

An asynchronous layer on top of Amazon's SimpleDB library.

  use Coro::Amazon::SimpleDB;

  my $sdb = Coro::Amazon::SimpleDB->new;
  $sdb->aws_access_key($aws_access_key_id);
  $sdb->aws_secret_access_key($aws_secret_access_key);
  $sdb->domain_name($aws_simpledb_domain);

  my $attributes = $sdb->async_get_items('name', 'rank', 'serial-number');
  my $full_name = join(' ', @{ $attributes->{name} }{'first', 'last'};

METHODS

new

Create and return a new instance. The usual idiom is:

  my $sdb = Coro::Amazon::SimpleDB->new(
    aws_access_key        => $key,
    aws_secret_access_key => $secret_key,
    domain_name           => $domain,
  );

  # ... do stuff with the instance

async_requests

The main method of the asynchronous interface. This method takes a list of item names, hash refs representing requests, or request objects and asynchronously requests them then polls and gathers the results, returning the response objects (or exception objects if the call failed) in an array ref ordered identically to the corresponding requests. The call will succeed even if some or all of the requests failed. It is up to the caller to check each entry in the response array to see if the call succeeded.

This method tries to keep the interface consistent with the Amazon::SimpleDB::Client interface. The 2 main differences are the assumption that a scalar argument is a request for all the attributes of the item name specified by the value, and an additional key, RequestType, which must be added to hash refs passed in to specify the request type. If an Amazon::SimpleDB::Model::*Request instance is passed in the correct method in the Amazon::SimpleDB::Client library is called automatically.

The RequestType key may be the full module name of the request class, the last part of the request class (e.g. GetAttributesRequest), or the appropriate method in Amazon::SimpleDB::Client (e.g. getAttributes).

Some examples:

  # $results will contain an array ref of
  # Amazon::SimpleDB::Model::GetAttributes::Reponse objects.
  my $results = $sdb->async_requests(qw( name rank serial-number ));

  # Same as above using hash refs as args.
  my $results = $sdb->async_requests(
    { RequestType => 'getAttributes', ItemName => 'name' },
    { RequestType => 'getAttributes', ItemName => 'rank' },
    { RequestType => 'getAttributes', ItemName => 'serial-number' },
  );

  # Same as above, but manually building our own objects.
  my $name_obj = Amazon::SimpleDB::Model::GetAttributesRequest->new({ ItemName => 'name' });
  my $rank_obj = Amazon::SimpleDB::Model::GetAttributesRequest->new({ ItemName => 'rank' });
  my $sn_obj = Amazon::SimpleDB::Model::GetAttributesRequest->new({ ItemName => 'serial-number' });
  my $results = $sdb->async_requests($name, $rank, $sn);

  # Combining several request types to be executed in a single
  # asynchronous batch.  It is inadvisable to both set and get the
  # same item in a single batch as the value returned is unspecified.
  my $results = $sdb->async_requests(
    { RequestType => 'getAttributes', ItemName => 'the-guide' },
    {
      RequestType => 'getAttributes',
      ItemName => 'heart-of-gold',
      AttributeName => [ 'specs', 'price' ],
    },
    {
      RequestType => 'putAttributes',
      ItemName => 'marvin',
      Attribute => [
        { Name => 'age-in-universe-lifetimes', Value => 2 },
        { Name => 'depression', Value => 'extreme' },
      ],
    },
  );

async_get_items

This is a convenience method for requesting items. It takes a list of item names and will return the corresponding attributes in a hash ref.

If an item with an identical name (either in the same domain or not) is requested multiple times it is undefined what the final result will be.

  my @keys = qw( ford arthur zaphod );
  my $results = $sdb->async_get_items(@keys);
  my $total_heads = sum map { $results->{$_}{head_count} } @keys;

poll

This method will poll the EV event loop until the pending attribute is empty. It is usually used internally but is available if users want to build their own asynchronous calls.

add_pending

A convenience method to add an item to the pending hash.

remove_pending

A convenience method to remove an item from the pending hash.

has_pending

Returns true if there are items in the pending hash.

bug

A debugging method which will print a message similar to a warn if the object has its DEBUG attribute set to a true value. If DEBUG is false it does nothing and immediately returns undef.

ATTRIBUTES

aws_access_key =head2 aws_secret_access_key

These are the AWS credentials providing access to your account. These should be available on security credentials page of the AWS portal.

domain_name

A default domain to use for requests. This may be over-ridden in requests passed as hash refs or objects.

sdb

The Amazon::SimpleDB::Client object to forward requests through. This is automatically created when first requested, but may also be passed in manually.

pending

A hash ref of pending coros. This is used internally to poll for completion of all asynchronous requests.

DEBUG

If set to a true value, the library will output some debugging and timing information.

CAVEATS

The Amazon SimpleDB client is required, but is not currently available via CPAN. It is available here as of 2010-10-20:

http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1136

AUTHOR

Dave Trischuk, <dtrischuk at cpan.org>

BUGS

Please report any bugs or feature requests to bug-coro-amazon-simpledb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Coro-Amazon-SimpleDB. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Coro::Amazon::SimpleDB

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2010 Campus Explorer http://www.campusexplorer.com/

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License Version 3.0 as published by the Free Software Foundation (see http://www.gnu.org/licenses/gpl.html); or the Artistic License 2.0 (see http://www.opensource.org/licenses/artistic-license-2.0.php).