NAME
SimpleDB::Class - An Object Relational Mapper (ORM) for the Amazon SimpleDB service.
VERSION
version 0.0100
SYNOPSIS
package Library;
use Moose;
extends 'SimpleDB::Class';
__PACKAGE__->load_namespaces();
1;
package Library::Books;
use Moose;
extends 'SimpleDB::Class::Domain';
__PACKAGE__->set_name('books');
__PACKAGE__->add_attributes({
title => { isa => 'Str', default => 'Untitled' },
publish_date => { isa => 'Int' },
isbn => { isa => 'Str' },
publisherId => { isa => 'Str' },
author => { isa => 'Str' },
});
__PACKAGE__->belongs_to('publisher', 'Library::Publishers', 'publisherId');
1;
package Library::Publishers;
use Moose;
extends 'SimpleDB::Class::Domain';
__PACKAGE__->set_name('publishers');
__PACKAGE__->add_attributes({
name => { isa => 'Str' },
});
__PACKAGE__->has_many('books', 'Library::Books', 'publisherId');
1;
use 5.010;
use Library;
use DateTime;
my $library = Library->new(access_key => 'xxx', secret_key => 'yyy');
my $specific_book = $library->domain('books')->find('id goes here');
my $books = $library->domain('publishers')->books;
my $books = $library->domain('books')->search({publish_date => DateTime->new(year=>2001)});
while (my $book = $books->next) {
say $book->title;
}DESCRIPTION
SimpleDB::Class gives you a way to persist your objects in Amazon's SimpleDB service search them easily. It hides the mess of web services, sudo SQL, and XML document formats that you'd normally need to deal with to use the service, and gives you a tight clean Perl API to access it.
On top of being a simple to use ORM that functions in a manner similar to DBIx::Class, SimpleDB::Class has some other niceties that make dealing with SimpleDB easier. It has cascading retries, which means it automatically attepts to retry failed requests (you have to plan for failure on the net). It automatically formats dates and integers for sortability in SimpleDB. It automatically casts date fields as DateTime objects. It uses Moose for everything, which makes it easy to use Moose's introspection features or method insertion features. It automatically generates UUID based ItemNames (unique IDs) if you don't want to supply an ID yourself. It automatically deals with the fact that you might have some attributes in your domains that aren't specified in your domain classes, and creates accessors and mutators for them on the fly at retrieval time. And finally result sets automatically fetch additional items from SimpleDB if a next token is provided.
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: "/aws.amazon.com/simpledb/"" in <a href="http:http://aws.amazon.com/simpledb/</a>>
secret_key
The secret access key given to you from Amazon.
access_key ( )
Returns the access key passed to the constructor.
secret_key ( )
Returns the secret key passed to the constructor.
domain_names ( )
Class method. Returns a hashref of the domain names and class names registered from subclassing SimpleDB::Class::Domain and calling set_name.
domain_classes ( [ list ] )
Class method. Returns a hashref of the domain class names and instances registered from subclassing SimpleDB::Class::Domain and calling set_name.
load_namespaces ( [ namespace ] )
Class method. Loads all the modules in the current namespace, so if you subclass SimpleDB::Class with a package called Library (as in the example provided), then everything in the Library namespace would be loaded automatically. Should be called to load all the modules you subclass, so you don't have to manually use each of them.
namespace
Specify a specific namespace like Library::SimpleDB if you don't want everything in the Library namespace to be loaded.
determine_domain_class ( moniker )
Given a domain name or class name, returns the class name associated with it.
moniker
A class name or a domain name that is a subclass of SimpleDB::Class::Domain. In the above example Library::Books or books would both return Library::Books.
determine_domain_instance ( classname )
Returns an instanciated SimpleDB::Class::Domain based upon it's class name.
classname
The classname to fetch an instance for. In the above example, Library::Books or Library::Publishers would both work.
domain ( moniker )
Returns an instanciated SimpleDB::Class::Domain based upon it's classname or domain name.
moniker
See determine_domain_class() for details.
construct_request ( action, [ params ] )
Returns a HTTP::Request object 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 "/docs.amazonwebservices.com/AmazonSimpleDB/2009-04-15/DeveloperGuide/"" in <a href="http:http://docs.amazonwebservices.com/AmazonSimpleDB/2009-04-15/DeveloperGuide/</a>>.
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.
list_domains ( )
Retrieves the list of domain names from your SimpleDB account and returns them as an array reference.
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.
action
See create_request() for details.
params
See create_request() for details.
PREREQS
This package requires the following modules:
XML::Simple LWP DateTime DateTime::Format::Strptime Moose MooseX::ClassAttribute Digest::SHA URI Time::HiRes Module::Find UUID::Tiny Exception::Class
TODO
This is an experimental class, and as such the API will likely change frequently over the next few releases. Still left to figure out:
- Caching. - Sub-searches from relationships. - Make puts and deletes asynchronous, since SimpleDB is eventually consistent, there's no reason to wait around for these operations to complete. - Creating subclasses of a domain based upon an attribute in a domain ( so you could have individuall dog breed object types all in a dogs domain for example). - Creating multi-domain objects ( so you can put each country's data into it's own domain, but still search all country-oriented data at once). - More exception handling. - More tests. - All the other stuff I forgot about or didn't know when I designed this thing.
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 robust that would allow me to easily map objects to SimpleDB Domain Items. If you're looking for a low level SimpleDB accessor, then you should check out these:
"/developer.amazonwebservices.com/connect/entry.jspa?externalID=1136"" in <a href="http:Amazon::SimpleD/a> - 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.
AUTHOR
JT Smith <jt_at_plainblack_com>
I have to give credit where credit is due: SimpleDB::Class is heavily inspired by DBIx::Class by Matt Trout (and others), and the Amazon::SimpleDB class distributed by Amazon itself (not to be confused with Amazon::SimpleDB written by Timothy Appnel).
LEGAL
SimpleDB::Class is Copyright 2009 Plain Black Corporation and is licensed under the same terms as Perl itself.