# File lib/amazon/aws/search.rb, line 71
        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

          # Set the following two variables from the config file. Will be
          # *nil* if not present in config file.
          #
          @api       = @config['api']
          @encoding   = @config['encoding']

          self.locale = locale
        end

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

          if nr_pages.is_a? Amazon::AWS::ResponseGroup
            raise ObsolescenceError, 'Request#search method no longer accepts response_group parameter.'
          end

          # Pre-0.8.0 user code may have passed *nil* as the second parameter,
          # in order to use the @response_group of the operation.
          #
          nr_pages ||= 1

          # Check to see whether a particular version of the API has been
          # requested. If so, overwrite Version with the new value.
          #
          parameters.merge!( { 'Version' => @api } ) if @api

          @query = Amazon::AWS.assemble_query( parameters, @encoding )
          page = Amazon::AWS.get_page( self )

          # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
          #
          page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'

          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 )

          # Another possible error results in a document containing nothing
          # but <Result>Internal Error</Result>. This occurs when a specific
          # version of the AWS API is requested, in combination with an
          # operation that did not yet exist in that version of the API.
          #
          # For example:
          #
          # http://ecs.amazonaws.com/onca/xml?AWSAccessKeyId=foo&Operation=VehicleSearch&Year=2008&ResponseGroup=VehicleMakes&Service=AWSECommerceService&Version=2008-03-03
          #
          if xml = doc.elements['Result']
            raise Amazon::AWS::Error::AWSError, xml.text
          end

          # 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

          if doc.elements['*/*[2]/TotalPages']
            total_pages = doc.elements['*/*[2]/TotalPages'].text.to_i

          # FIXME: ListLookup and MultipleOperation (and possibly others) have
          # TotalPages nested one level deeper. I should take some time to
          # ensure that all operations that can return multiple results pages
          # are covered by either the 'if' above or the 'elsif' here.
          #
          elsif doc.elements['*/*[2]/*[2]/TotalPages']
            total_pages = doc.elements['*/*[2]/*[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

          if PAGINATION.key? operation.kind
            page_parameter = PAGINATION[operation.kind]['parameter']
            max_pages = PAGINATION[operation.kind]['max_page']
          else
            page_parameter = 'ItemPage'
            max_pages = 400
          end

          # 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(
                      parameters.merge( { page_parameter => page_nr } ),
                      @encoding)
            page = Amazon::AWS.get_page( self )

            # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
            #
            page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'

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