def set_json_response_object( self, json_object_IN ):
        
        '''
        Accepts JSON response object (name-value pairs) from call to OpenCalais
           REST API.  Stores it internally, then parses it and break out pieces
           so it is easier to work with.
        '''
        
        # return reference
        instance_OUT = None
        
        # declare variables
        me = "set_json_response_object"
        my_logger = None
        json_string = ""
        response_json_root = None
        item_counter = -1
        current_key = ""
        current_object = None
        current_type = ""
        current_type_group = ""
        doc_object = None
        current_status = ""
        
        # get logger
        my_logger = self.get_logger()
        
        # first, remind myself what the JSON looks like.
        #json_string = JSONHelper.pretty_print_json( json_object_IN )
        #my_logger.debug( "In " + me + ": outputting whole JSON document:" )
        #my_logger.debug( json_string )
        
        # store JSON response in "response_json_root" variable.
        response_json_root = json_object_IN
        
        # loop over the list of top-level things.  It should be a set of
        #    name-value pairs where the value is another structured JSON object.
        for item_counter, current_key in enumerate( response_json_root ):
        
            # grab JSON for the key.
            current_object = response_json_root[ current_key ]
            
            # get type group
            current_type_group = JSONHelper.get_json_object_property( current_object, self.JSON_NAME_ITEM_TYPE_GROUP )
            
            # get current entity type.
            current_type = JSONHelper.get_json_object_property( current_object, self.JSON_NAME_ITEM_TYPE )
            
            if ( self.DEBUG_FLAG == True ):

                # log it.
                my_logger.debug( "In " + me + ": #" + str( item_counter ) + " (type group: " + str( current_type_group ) + "; type: " + str( current_type ) + ") = " + current_key )
                
            #-- END DEBUG --#
            
            # if doc, store the doc off in separate reference for easy access.
            if ( current_key == self.JSON_NAME_DOC ):
            
                # store off the doc.
                self.set_doc( current_object )
                
                # output, just to make sure I have what I think I have.
                #json_string = JSONHelper.pretty_print_json( current_object )
                #my_logger.debug( "In " + me + ": outputting JSON \"doc\" object:" )
                #my_logger.debug( json_string )
            
            #-- END check to see if "doc" JSON --#
            
            # add to dict of type groups to items
            current_status = self.add_item_to_type_group_dict( current_key, current_object )
            
            if ( self.DEBUG_FLAG == True ):

                my_logger.debug( "In " + me + ": added to type group map: " + current_status )
                
            #-- END DEBUG --#
            
            # add to dict of types to items
            current_status = self.add_item_to_type_dict( current_key, current_object )
        
            if ( self.DEBUG_FLAG == True ):

                my_logger.debug( "In " + me + ": added to type map: " + current_status )

            #-- END DEBUG --#


        #-- END loop over top-level keys in JSON --#
        
        # store root in instance variable
        self.json_response_object = response_json_root
        instance_OUT = self.json_response_object
        
        if ( self.DEBUG_FLAG == True ):

            # try retrieving doc entity directly from root element.
            doc_object = self.get_item_from_response( self.JSON_NAME_DOC )
    
            # output, just to make sure I have what I think I have.
            json_string = JSONHelper.pretty_print_json( doc_object )
            my_logger.debug( "In " + me + ": outputting JSON \"doc\" object from lookup:" )
            my_logger.debug( json_string )
        
        #-- END DEBUG --#
        
        return instance_OUT

    #-- END method set_json_response_object() --#


#-- END class OpenCalaisV2ApiResponse --#
        # save to database
        tweet_db.save()
        
        #------------------------------------------------------------------------
        # JSON
        #------------------------------------------------------------------------

        # save JSON to database?
        if do_save_json_to_database == True:

            tweet_json = tweetnet.models.Tweet_JSON()
            tweet_json.tweet = tweet_db
            
            # convert JSON to pretty-printed string
            current_tweet_JSON_string = JSONHelper.pretty_print_json( current_tweet )
            
            # store JSON string
            tweet_json.tweet_json = current_tweet_JSON_string
    
            # save to database.
            tweet_json.save()
            
        #-- END check to see if we save JSON to database --#

    #-- END try-except to see if deleted tweet. --#
    
    if ( tweet_counter % 100 ) == 0:
    
        # yes - print a brief message
        print( "====> tweet count = " + str( tweet_counter ) )