/**
 * Exposes a series of metrics regarding the resolution of a natural-id
 * to its corresponding identifier.  This involves metrics about the
 * execution of the SQL to perform the resolution, as well as metrics about
 * the caching of that resolutin (if enabled).
 *
 * @author Steve Ebersole
 */
public interface NaturalIdStatistics {
	/**
	 * If second-level caching is enabled, returns the number of times
	 * Hibernate has looked for a resolution in the cache and found
	 * it (cache hit).  Returns -1 if caching is disabled.
	 * 
	 * @return The number of second-level cache hits. or -1
	 */
	long getCacheHitCount();

	/**
	 * If second-level caching is enabled, returns the number of times
	 * Hibernate has looked for a resolution in the cache and not found
	 * it (cache miss).  Returns -1 if caching is disabled.
	 *
	 * @return The number of second-level cache misses. or -1
	 */
	long getCacheMissCount();

	/**
	 * If second-level caching is enabled, returns the number of times
	 * Hibernate has stored a resolution into the cache.  Returns -1 
	 * if caching is disabled.
	 *
	 * @return The number of second-level cache puts. or -1
	 */
	long getCachePutCount();

	/**
	 * How many times has Hibernate had to execute the SQL for
	 * looking up the {@code NaturalId->Id} mapping for this
	 * entity type?
	 * <p/>
	 * This is generally indicative of a corresponding {@link #getCacheMissCount()}
	 * and a corresponding {@link #getCachePutCount()}.
	 *
	 * @return The number of time that query has been executed.
	 */
	long getQueryExecutionCount();

	/**
	 * When we have had to execute the SQL query ({@link #getQueryExecutionCount()}),
	 * how long has it taken on average?
	 *
	 * @return The average execution time for the {@code NaturalId->Id} query?
	 */
	long getQueryExecutionAvgTime();

	/**
	 * When we have had to execute the {@code NaturalId->Id} query,
	 * what is the longest amount of time it has taken (in milliseconds)?
	 *
	 * @return The longest execution time for the {@code NaturalId->Id} query?
	 */
	long getQueryExecutionMaxTime();

	/**
	 * When we have had to execute the {@code NaturalId->Id} query,
	 * what is the least amount of time it has taken (in milliseconds)?
	 *
	 * @return The smallest execution time for the {@code NaturalId->Id} query?
	 */
	long getQueryExecutionMinTime();
}