# File lib/amazon/aws/search.rb, line 54
        def initialize(key_id=nil, associate=nil, locale=nil, cache=nil,
                       user_agent=USER_AGENT)

          @config ||= Amazon::Config.new

          def_locale = locale
          locale = 'us' unless locale
          locale.downcase!

          key_id ||= @config['key_id']
          cache = @config['cache'] if cache.nil?

          # Take locale from config file if no locale was passed to method.
          #
          if @config.key?( 'locale' ) && ! def_locale
            locale = @config['locale']
          end
          validate_locale( locale )

          if key_id.nil?
            raise AccessKeyIdError, 'key_id may not be nil'
          end

          @key_id     = key_id
          @tag       = associate || @config['associate'] || DEF_ASSOC[locale]
          @user_agent = user_agent
          @cache      = unless cache == 'false' || cache == false
                          Amazon::AWS::Cache.new( @config['cache_dir'] )
                        else
                          nil
                        end
          self.locale = locale
        end

# File lib/amazon/aws/search.rb, line 193
        def search(operation, response_group, nr_pages=1)
          q_params = Amazon::AWS::SERVICE.
                       merge( { 'AWSAccessKeyId' => @key_id,
                                'AssociateTag'   => @tag } ).
                       merge( operation.params ).
                       merge( response_group.params )

          query = Amazon::AWS.assemble_query( q_params )
          page = Amazon::AWS.get_page( self, query )
          doc = Document.new( page )

          # Some errors occur at the very top level of the XML. For example,
          # when no Operation parameter is given. This should not be possible
          # with user code, but occurred during debugging of this library.
          #
          error_check( doc )

          # Fundamental errors happen at the OperationRequest level. For
          # example, if an invalid AWSAccessKeyId is used.
          #
          error_check( doc.elements['*/OperationRequest'] )

          # Check for parameter and value errors deeper down, inside Request.
          #
          if operation.kind == 'MultipleOperation'

            # Everything is a level deeper, because of the
            # <MultiOperationResponse> container.
            #
            # Check for errors in the first operation.
            #
            error_check( doc.elements['*/*/*/Request'] )

            # Check for errors in the second operation.
            #
            error_check( doc.elements['*/*[3]/*/Request'] )

            # If second operation is batched, check for errors in its 2nd set
            # of results.
            #
            if batched = doc.elements['*/*[3]/*[2]/Request']
              error_check( batched )
            end
          else
            error_check( doc.elements['*/*/Request'] )

            # If operation is batched, check for errors in its 2nd set of
            # results.
            #
            if batched = doc.elements['*/*[3]/Request']
              error_check( batched )
            end
          end

          # FIXME: This doesn't work if a MultipleOperation was used, because
          # <TotalPages> will be nested one level deeper. It's therefore
          # currently only possible to return the first page of results
          # for operations combined in a MultipleOperation.
          #
          if doc.elements['*/*[2]/TotalPages']
            total_pages = doc.elements['*/*[2]/TotalPages'].text.to_i
          else
            total_pages = 1
          end

          # Create a root AWS object and walk the XML response tree.
          #
          aws = AWS::AWSObject.new( operation )
          aws.walk( doc )
          result = aws

          # If only one page has been requested or only one page is available,
          # we can stop here. First yield to the block, if given.
          #
          if nr_pages == 1 || ( tp = total_pages ) == 1
             yield result if block_given?
             return result
          end

          # Limit the number of pages to the maximum number available.
          #
          nr_pages = tp.to_i if nr_pages == :ALL_PAGES || nr_pages > tp.to_i

          # Iterate over pages 2 and higher, but go no higher than MAX_PAGES.
          #
          2.upto( nr_pages < MAX_PAGES ? nr_pages : MAX_PAGES ) do |page_nr|
            query = Amazon::AWS.assemble_query(
                      q_params.merge( { 'ItemPage' => page_nr } ) )
            page = Amazon::AWS.get_page( self, query )
            doc = Document.new( page )

            # Check for errors.
            #
            error_check( doc.elements['*/OperationRequest'] )
            error_check( doc.elements['*/*/Request'] )

            # Create a new AWS object and walk the XML response tree.
            #
            aws = AWS::AWSObject.new
            aws.walk( doc )

            # When dealing with multiple pages, we return not just an
            # AWSObject, but an array of them.
            #
            result = [ result ] unless result.is_a? Array

            # Append the new object to the array.
            #
            result << aws
          end

          # Yield each object to the block, if given.
          #
          result.each { |r| yield r } if block_given?

          result
        end