# This class is the starting point for working with Amazon SimpleDB.

#

# To use Amazon SimpleDB you must first

# [sign up here](http://aws.amazon.com/simpledb/).

#

# For more information about Amazon SimpleDB:

#

# * [Amazon SimpleDB](http://aws.amazon.com/simpledb/)

# * [Amazon SimpleDB Documentation](http://aws.amazon.com/documentation/simpledb/)

#

# # Credentials

#

# You can setup default credentials for all AWS services via

# AWS.config:

#

# AWS.config(

# :access_key_id => 'YOUR_ACCESS_KEY_ID',

# :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

#

# Or you can set them directly on the SimpleDB interface:

#

# sdb = AWS::SimpleDB.new(

# :access_key_id => 'YOUR_ACCESS_KEY_ID',

# :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

#

# # Understanding the SimpleDB Interface

#

# SimpleDB stores data in a hierarchy of:

#

# Domains > Items > Attributes

#

# These are modeled with the following classes:

#

# * {DomainCollection}

# * {Domain}

# * {ItemCollection}

# * {Item}

# * {AttributeCollection}

# * {Attribute}

#

# The collection classes listed above make it easy to enumerate,

# the objects they represent. They also make it easy to perform

# bulk operations on all objects in that collection.

#

# # Domains

#

# Domains are like database tables. A domain must exist before you can

# write to it. To create a domain:

#

# sdb = SimpleDB.new

# domain = sdb.domains.create('mydomain')

#

# For more information about working with domains see {DomainCollection}

# and {Domain}.

#

# # Items & Attributes

#

# Items exist in SimpleDB when they have attributes. You can delete an

# item by removing all of its attributes. You create an item by adding

# an attribute to it.

#

# The following example illustrates how you can reference an item that

# does not exist yet:

#

# sdb = SimpleDB.new

#

# # this domain is empty, it has no items

# domain = sdb.domains.create('newdomain')

# domain.items.collect(&:name)

# #=> []

#

# # this item doesn't exist yet, so it has no attributes

# item = domain.items['newitem']

# item.attributes.collect(&:name)

# #=> []

#

# # the item has no attributes

# tags = item.attributes['tags']

# tags.values

# #=> []

#

# To create the item in SimpleDB you just need to add an attribute.

#

# tags.add %w(first new)

#

# domain.items.collect(&:name)

# #=> ['newitem']

#

# item.attributes.collect(&:name)

# #=> ['tags']

#

# tags.values

# #=> ['first', 'new']

#

# For more information about working with items and attributes, see:

#

# * {ItemCollection}

# * {Item}

# * {AttributeCollection}

# * {Attribute}

#

# # Lazy Execution

#

# Requests are not made until necessary. This means you can drill down

# all the way to an attribute, by name, without making any requests

# to SimpleDB.

#

# # makes no request to SimpleDB

# sdb = SimpleDB.new

# colors = sdb.domains['mydomain'].items['car'].attributes['colors']

#

# # one request to get the values for 'colors'

# puts colors.values

#

# # one request to add blue and green

# colors.add 'blue', 'green'

#

# # one request to delete the colors attribute

# colors.delete

#

# @!attribute [r] client

# @return [Client] the low-level SimpleDB client object

class SimpleDB

autoload :Attribute, 'aws/simple_db/attribute'

autoload :AttributeCollection, 'aws/simple_db/attribute_collection'

autoload :Client, 'aws/simple_db/client'

autoload :ConsistentReadOption, 'aws/simple_db/consistent_read_option'

autoload :DeleteAttributes, 'aws/simple_db/delete_attributes'

autoload :Domain, 'aws/simple_db/domain'

autoload :DomainCollection, 'aws/simple_db/domain_collection'

autoload :DomainMetadata, 'aws/simple_db/domain_metadata'

autoload :Errors, 'aws/simple_db/errors'

autoload :ExpectConditionOption, 'aws/simple_db/expect_condition_option'

autoload :Item, 'aws/simple_db/item'

autoload :ItemCollection, 'aws/simple_db/item_collection'

autoload :ItemData, 'aws/simple_db/item_data'

autoload :PutAttributes, 'aws/simple_db/put_attributes'

include Core::ServiceInterface

endpoint_prefix 'sdb'

# Returns a collection object that represents the domains in your

# account.

#

# @return [DomainCollection] Returns a collection representing all your

# domains.

def domains

DomainCollection.new(:config => config)

end

# Call this method with a block. Code executed inside the block

# make consistent reads until the block ends.

#

# AWS::SimpleDB.consistent_reads do

# # ...

# end

#

# ### Other Modes

#

# You can also use this same function to disable consistent reads inside

# a block. This is useful if you have consistent reads enabled by

# default:

#

# AWS::SimpleDB.consistent_reads(false) do

# # ...

# end

#

# @param [Boolean] state (true) When true, all SimpleDB read operations

# will be consistent reads inside the block. When false, all

# reads operations will not be consistent reads. The previous state

# will be restored after the block executes.

# @return Returns the final block value.

def self.consistent_reads state = true, &block

begin

prev_state = Thread.current['_simple_db_consistent_reads_']

Thread.current['_simple_db_consistent_reads_'] = state

yield

ensure

Thread.current['_simple_db_consistent_reads_'] = prev_state

end

end

# @return [Boolean] Returns true if we are inside an AWS::SimpleDB

# #consistent_reads method block.

# @api private

def self.in_consistent_reads_block?

!Thread.current['_simple_db_consistent_reads_'].nil?

end

# @return [Boolean] Returns true if the consistent_reads block has

# a true state, false otherwise.

# @api private

def self.consistent_reads_state

Thread.current['_simple_db_consistent_reads_']

end

end