JT Smith > SimpleDB-Class > SimpleDB::Class

Download:
SimpleDB-Class-1.0503.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 1.0503   Source  

NAME ^

SimpleDB::Class - An Object Relational Mapper (ORM) for the Amazon SimpleDB service.

VERSION ^

version 1.0503

SYNOPSIS ^

 package Library;

 use Moose;
 extends 'SimpleDB::Class';
 
 __PACKAGE__->load_namespaces();

 1;

 package Library::Book;

 use Moose;
 extends 'SimpleDB::Class::Item';

 __PACKAGE__->set_domain_name('book');
 __PACKAGE__->add_attributes(
     title          => { isa => 'Str', default => 'Untitled' },
     publish_date   => { isa => 'Date' },
     edition        => { isa => 'Int', default => 1 },
     isbn           => { isa => 'Str' },
     publisherId    => { isa => 'Str' },
     author         => { isa => 'Str' },
 );
 __PACKAGE__->belongs_to('publisher', 'Library::Publisher', 'publisherId');

 1;

 package Library::Publisher;

 use Moose;
 extends 'SimpleDB::Class::Item';

 __PACKAGE__->set_domain_name('publisher');
 __PACKAGE__->add_attributes(
     name   => { isa => 'Str' },
 );
 __PACKAGE__->has_many('books', 'Library::Book', 'publisherId');

 1;

 use 5.010;
 use Library;
 use DateTime;

 my $library = Library->new(access_key => 'xxx', secret_key => 'yyy', cache_servers=>\@servers );
  
 my $specific_book = $library->domain('book')->find('id goes here');

 my $books = $library->domain('publisher')->find($id)->books;
 my $books = $library->domain('book')->search( where => {publish_date => ['between', DateTime->new(year=>2001), DateTime->new(year=>2003)]} );
 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, pseudo 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:

Eventual Consistency

SimpleDB is eventually consistent, which means that if you do a write, and then read directly after the write you may not get what you just wrote. SimpleDB::Class gets around this problem for the post part because it caches all SimpleDB::Class::Items in memcached. That is to say that if an object can be read from cache, it will be. The one area where this falls short are some methods in SimpleDB::Class::Domain and SimpleDB::Class::ResultSet that perform searches on the database which look up items based upon their attributes rather than based upon id. Even in those cases, once an object is located we try to pull it from cache rather than using the data SimpleDB gave us, simply because the cache may be more current. However, a search result may return too few (inserts pending) or too many (deletes pending) results in SimpleDB::Class::ResultSet, or it may return an object which no longer fits certain criteria that you just searched for (updates pending). As long as you're aware of it, and write your programs accordingly, there shouldn't be a problem.

At the end of February 2010 Amazon added a ConsistentRead option to SimpleDB, which means you don't have to care about eventual consistency if you wish to sacrifice some performance. We have exposed this as an option for you to turn on in the methods like search in SimpleDB::Class::Domain where you have to be concerned about eventual consistency.

Does all this mean that this module makes SimpleDB as ACID compliant as a traditional RDBMS? No it does not. There are still no locks on domains (think tables), or items (think rows). So you probably shouldn't be storing sensitive financial transactions in this. We just provide an easy to use API that will allow you to more easily and a little more safely take advantage of Amazon's excellent SimpleDB service for things like storing logs, metadata, and game data.

For more information about eventual consistency visit http://en.wikipedia.org/wiki/Eventual_consistency or the eventual consistency section of the Amazon SimpleDB Developer's Guide at http://docs.amazonwebservices.com/AmazonSimpleDB/2009-04-15/DeveloperGuide/EventualConsistencySummary.html.

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.

cache_servers

An array reference of cache servers. See SimpleDB::Class::Cache for details.

simpledb_uri

An optional URI object to connect to an alternate SimpleDB server. See also "simpledb_uri" in SimpleDB::Client.

domain_prefix

An optional string that is prepended to all domain names wherever they are used in the system.

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.

cache_servers ( )

Returns the cache server array reference passed into the constructor.

cache ( )

Returns a reference to the SimpleDB::Class::Cache instance.

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, if any. See also "simpledb_uri" in SimpleDB::Client.

has_simpledb_uri ( )

Returns a boolean indicating whether the user has overridden the URI.

domain_prefix ( )

Returns the value passed into the constructor.

has_domain_prefix ( )

Returns a boolean indicating whether the user has specified a domain_prefix.

add_domain_prefix ( domain )

If the domain_prefix is set, this method will apply it do a passed in domain name. If it's not, it will simply return the domain anme as is.

NOTE: This is used mostly internally to SimpleDB::Class, so unless you're extending SimpleDB::Class itself, rather than just using it, you don't have to use this method.

domain

The domain to apply the prefix to.

http ( )

Returns the SimpleDB::Client instance used to connect to the SimpleDB service.

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 ( moniker )

Returns an instanciated SimpleDB::Class::Domain based upon its SimpleDB::Class::Item classname or its domain name.

moniker

Can either be the SimpleDB::Class::Item subclass name, or the domain name.

list_domains ( )

Retrieves the list of domain names from your SimpleDB account and returns them as an array reference.

PREREQS ^

This package requires the following modules:

JSON Sub::Name DateTime DateTime::Format::Strptime Moose MooseX::Types MooseX::ClassAttribute Module::Find UUID::Tiny Exception::Class Memcached::libmemcached Clone SimpleDB::Client

TODO ^

Still left to figure out:

SUPPORT ^

Repository

http://github.com/plainblack/SimpleDB-Class

Bug Reports

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

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).

LEGAL ^

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

syntax highlighting: