package com.atlassian.stash.internal.db;

import com.google.common.base.Supplier;

import javax.annotation.Nonnull;
import java.sql.Connection;

/**
 * Allows callers to retrieve detailed information about the connected database.
 *
 * @since 2.2
 */
public interface DatabaseSupplier extends Supplier<DetailedDatabase> {

    /**
     * Retrieves details for the configured database. These details are drawn from the database itself, not inferred
     * from the JDBC driver in use.
     *
     * @return details for the configured database
     * @throws org.springframework.jdbc.CannotGetJdbcConnectionException if a connection cannot be opened to the
     *                                                                   database using the configured driver
     * @throws org.springframework.dao.DataRetrievalFailureException if metadata cannot be loaded for the configured
     *                                                               database
     */
    @Nonnull
    DetailedDatabase get();

    /**
     * Retrieves details for the connected database. These details are drawn from the database itself, using the
     * provided connection, not inferred from the JDBC driver providing the connection.
     *
     * @param connection an <i>open</i> connection to the database
     * @return details for the connected database
     * @since 2.4.2
     * @throws org.springframework.dao.DataRetrievalFailureException if metadata cannot be loaded for the connected
     *                                                               database, or the provided connection is closed
     */
    @Nonnull
    DetailedDatabase getForConnection(@Nonnull Connection connection);
}
