/ 
SimpleDB-Client-1.0600
River stage one • 2 direct dependents • 4 total dependents
/ SimpleDB::Client

NAME

SimpleDB::Client - The network interface to the SimpleDB service.

VERSION

version 1.0600

SYNOPSIS

use SimpleDB::Client;

my $sdb = SimpleDB::Client->new(secret_key=>'abc', access_key=>'123');

# create a domain
my $hashref = $sdb->send_request('CreateDomain', {DomainName => 'my_things'});

# insert attributes
my $hashref = $sdb->send_request('PutAttributes', {
    DomainName             => 'my_things', 
    ItemName               => 'car',
    'Attribute.1.Name'     => 'color',
    'Attribute.1.Value'    => 'red',
    'Attribute.1.Replace'  => 'true',
});

# get attributes
my $hashref = $sdb->send_request('GetAttributes', {
    DomainName             => 'my_things', 
    ItemName               => 'car',
});

# search attributes
my $hashref = $sdb->send_request('Select', {
    SelectExpression       => q{select * from my_things where color = 'red'},
});

DESCRIPTION

This class will let you quickly and easily inteface with AWS SimpleDB. It throws exceptions from SimpleDB::Client::Exception. It's very light weight. Although we haven't run any benchmarks on the other modules, it should outperform any of the other Perl modules that exist today.

METHODS

The following methods are available from this class.

new ( params )

params

A hash containing the parameters to pass in to this method.

access_key

The access key given to you from Amazon when you sign up for the SimpleDB service at this URL: http://aws.amazon.com/simpledb/

secret_key

The secret access key given to you from Amazon.

simpledb_uri

The constructor that SimpleDB::Client will connect to. Defaults to:

URI->new('https://sdb.amazonaws.com/')

access_key ( )

Returns the access key passed to the constructor.

secret_key ( )

Returns the secret key passed to the constructor.

simpledb_uri ( )

Returns the URI object passed into the constructor that SimpleDB::Client will connect to. Defaults to:

URI->new('https://sdb.amazonaws.com/')

user_agent ( )

Returns the LWP::UserAgent object that is used to connect to SimpleDB. It's cached here so it doesn't have to be created each time.

construct_request ( action, [ params ] )

Returns a string that contains the HTTP post data ready to make a request to SimpleDB. Normally this is only called by send_request(), but if you want to debug a SimpleDB interaction, then having access to this method is critical.

action

The action to perform on SimpleDB. See the "Operations" section of the guide located at http://docs.amazonwebservices.com/AmazonSimpleDB/2009-04-15/DeveloperGuide/.

params

Any extra prameters required by the operation. The normal parameters of Action, AWSAccessKeyId, Version, Timestamp, SignatureMethod, SignatureVersion, and Signature are all automatically provided by this method.

send_request ( action, [ params ] )

Creates a request, and then sends it to SimpleDB. The response is returned as a hash reference of the raw XML document returned by SimpleDB. Automatically attempts 5 cascading retries on connection failure.

Throws SimpleDB::Client::Exception::Response and SimpleDB::Client::Exception::Connection.

action

See create_request() for details.

params

See create_request() for details.

handle_response ( response )

Returns a hashref containing the response from SimpleDB.

Throws SimpleDB::Client::Exception::Response.

response

The HTTP::Response object created by the send_request method.

PREREQS

This package requires the following modules:

XML::Fast LWP Time::HiRes Crypt::SSLeay Moose Digest::SHA URI Exception::Class

SUPPORT

Repository

http://github.com/rizen/SimpleDB-Client

Bug Reports

http://rt.cpan.org/Public/Dist/Display.html?Name=SimpleDB-Client

SEE ALSO

There are other packages you can use to access SimpleDB. I chose not to use them because I wanted something a bit more lightweight that I could build SimpleDB::Class on top of so I could easily map objects to SimpleDB Domain Items. If you're looking for a low level SimpleDB accessor and for some reason this module doesn't cut the mustard, then you should check out these:

Amazon::SimpleDB (http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1136)

A complete and nicely functional low level library made by Amazon itself.

Amazon::SimpleDB

A low level SimpleDB accessor that's in its infancy and may be abandoned, but appears to be pretty functional, and of the same scope as Amazon's own module.

In addition to clients, there is at least one other API compatible server out there that basically lets you host your own SimpleDB if you don't want to put it in Amazon's cloud. It's called M/DB. You can read more about it here: http://gradvs1.mgateway.com/main/index.html?path=mdb. Though I haven't tested it, since it's API compatible, you should be able to use it with both this module and SimpleDB::Class.

AUTHOR

JT Smith <jt_at_plainblack_com>

I have to give credit where credit is due: SimpleDB::Client is heavily inspired by the Amazon::SimpleDB class distributed by Amazon itself (not to be confused with Amazon::SimpleDB written by Timothy Appnel).

LEGAL

SimpleDB::Client is Copyright 2009-2010 Plain Black Corporation (http://www.plainblack.com/) and is licensed under the same terms as Perl itself.