/* ************************************************************************
#
#  DivConq
#
#  http://divconq.com/
#
#  Copyright:
#    Copyright 2012 eTimeline, LLC. All rights reserved.
#
#  License:
#    See the license.txt file in the project's top-level directory for details.
#
#  Authors:
#    * Andy White
#
************************************************************************ */
package divconq.db;

import divconq.lang.OperationResult;
import divconq.struct.CompositeStruct;

/**
 * All requests to the dcDb must implement this interface.  Each request is required
 * to provide essentials details to the database.
 *  
 * @author Andy
 *
 */
public interface IDatabaseRequest {
	/**
	 * A request is composed of a procedure name and a collection of
	 * java objects (CompositeStruct) as parameters.  Typically parameters
	 * are either a ListStruct or a RecordStruct.
	 * 
	 * @return parameters for this request
	 */
	CompositeStruct getDatabaseParams(IDatabaseManager dbm);
	
	/**
	 * If the parameters for this request will take a lot of memory (>64kb)
	 * then let the database know by returning true.  It may then process
	 * the request differently to save space.  
	 * 
	 * @return true if the parameters might take a lot of space
	 */
	boolean isBulkyRequest();
	
	/**
	 * Does this request make any updates to the database, or is it purely
	 * a query.
	 * 
	 * @return true if data is (supposed to be) altered by this request
	 */
	boolean isDatabaseUpdate();
	
	/**
	 * @return the name of the stored procedure to call
	 */
	String getProcedure();

	/**
	 * Called by DB Manager after the request is submitted, used to verify that
	 * the request has all the content required to call the given stored procedure. 
	 * 
	 * @param or log of validation messages
	 */
	void validate(OperationResult or);

	/**
	 * Called by dcDb after the request has been processed and a result is available.
	 * This provides an opportunity for a interactive request object that can react to
	 * and elaborate on previous requests.
	 *    
	 * @param result
	 */
	void process(DatabaseResult result);
}
