001/*
002 * ============================================================================
003 *  Copyright © 2002-2022 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.sql;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import java.sql.Connection;
023
024import org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026import org.tquadrat.foundation.lang.Status;
027
028/**
029 *  <p>{@summary Returns a database connection.}</p>
030 *  <p>Implementations of this interface can be used when different sources for
031 *  a database connection are possible for an instance that needs one.</p>
032 *  <p>This is a functional interface whose functional method is
033 *  {@link #getConnection()}</p>
034 *
035 *  @version $Id: ConnectionProvider.java 1024 2022-03-10 09:57:43Z tquadrat $
036 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
037 *  @UMLGraph.link
038 *  @since 0.1.0
039 */
040@FunctionalInterface
041@ClassVersion( sourceVersion = "$Id: ConnectionProvider.java 1024 2022-03-10 09:57:43Z tquadrat $" )
042@API( status = STABLE, since = "0.1.0" )
043public interface ConnectionProvider
044{
045        /*---------*\
046    ====** Methods **==========================================================
047        \*---------*/
048    /**
049     *  <p>{@summary Returns a valid database connection.}</p>
050     *  <p>In case of an error, the method will set the
051     *  {@link Status#errorCode() errorCode}
052     *  attribute of the returned
053     *  {@link Status}
054     *  object.</p>
055     *
056     *  @note   The implementations of this method will never throw an
057     *      exception.
058     *
059     *  @return An instance of
060     *      {@link org.tquadrat.foundation.lang.Status}
061     *      that holds the retrieved connection.
062     */
063    public Status<Connection,Throwable> getConnection();
064}
065//  interface ConnectionProvider
066
067/*
068 *  End of File
069 */