001/* 
002 * JKNIV, whinstone one contract to access your database.
003 * 
004 * Copyright (C) 2017, the original author or authors.
005 *
006 * This library is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 2.1 of the License.
010 * 
011 * This library is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 * 
016 * You should have received a copy of the GNU Lesser General Public
017 * License along with this library; if not, write to the Free Software Foundation, Inc., 
018 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
019 */
020package net.sf.jkniv.whinstone;
021
022import java.sql.CallableStatement;
023import java.sql.PreparedStatement;
024import java.sql.ResultSet;
025import java.sql.Statement;
026
027import net.sf.jkniv.exception.HandleableException;
028import net.sf.jkniv.sqlegance.transaction.Isolation;
029import net.sf.jkniv.whinstone.transaction.Transactional;
030import net.sf.jkniv.whinstone.types.RegisterType;
031
032
033/**
034 * Responsible to open connections with a specific database,
035 * could be a DataSource, DriverManager, SpringDataSource manager...
036 * 
037 * @author Alisson Gomes
038 *
039 */
040public interface ConnectionFactory
041{
042    /**
043     * Attempts to establish a connection to the database
044     * @return a Connection from the URL or DataSource
045     * @throws net.sf.jkniv.sqlegance.RepositoryException if cannot establish a connection
046     */
047    ConnectionAdapter open();
048
049    ConnectionFactory with(HandleableException handlerException);
050
051    /**
052     * Attempts to establish a connection to the database with specific isolation 
053     * @param isolation isolation level from transaction
054     * @return a Connection from the URL or DataSource
055     * @throws net.sf.jkniv.sqlegance.RepositoryException if cannot establish a connection
056     */
057    ConnectionAdapter open(Isolation isolation);
058    
059    /**
060     * Create new Transaction Manager for JDBC transactions
061     * @return a LOCAL, GLOBAL or EJB transaction manager.
062     */
063    Transactional getTransactionManager();
064    
065    /**
066     * Name from repository context
067     * @return name of context
068     */
069    String getContextName();
070
071    /**
072     * <code>null-safe</code> close connection.
073     * Throws {@code SQLException} is logged as warning.
074     * @param conn connection to close
075     */
076    void close(ConnectionAdapter conn);
077        
078    /**
079     * <code>null-safe</code> close PreparedStatement.
080     * Throws {@code SQLException} is logged as warning.
081     * @param stmt statement to close
082     */
083    void close(PreparedStatement stmt);
084    
085    /**
086     * <code>null-safe</code> close Statement.
087     * Throws {@code SQLException} is logged as warning.
088     * @param stmt statement to close
089     */
090    void close(Statement stmt);
091    
092    /**
093     * <code>null-safe</code> close ResultSet.
094     * Throws {@code SQLException} is logged as warning.
095     * @param rs ResultSet to close
096     */
097    void close(ResultSet rs);
098    
099    /**
100     * <code>null-safe</code> close CallableStatement.
101     * Throws {@code SQLException} is logged as warning.
102     * @param call CallableStatement to close
103     */
104    void close(CallableStatement call);
105
106}