/*
   XBN Java:  Generically useful, non-GUI Java code.
   http://sourceforge.net/projects/xbnjava

   Copyright (C) 1997-2003, Jeff Epstein
   All rights reserved.

   Modifications: No

   Redistribution in binary form, with or without modifications, are permitted provided that the following conditions are met:

      * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
      * If modifications are made to source code then this license should indicate that fact in the "Modifications" section above.
      * Neither the author, nor the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   [NOTE:  This license contains NO advertising clause.]
 */
package xbn.db;

   import xbn.output.Outputter;

   import java.sql.Connection;
   import java.sql.DriverManager;
   import java.sql.SQLException;

/**
   <P>Convenience class for handling a single database connection created from the user/pass/JDBC characteristics.  See java.sql.<A HREF="~JD~conn~EJD~">Connection</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/db/DBConnection.java">DBConnection.java</A>. &nbsp;<B>Example code</B> &nbsp;<A HREF="../../xbn_examples/db/XmplDBConnection.html">XmplDBConnection</A>.</I></CODE></P>

   <P>Note:  When you set a connection directly, via <A HREF="DBConnDirect.html">DBConnDirect</A>.<A HREF="~JD~dbcd#setConnection(conn)~EJD~">setConnection</A>, be aware of the following.  If that connection has a different username/password/JDBC characteristics than was passed into the <A HREF="~JD~dbc(s,s,s,s,s,optr)~EJD~">constructor of this class</A>, then if you <A HREF="DBConnDirect.html#disconnect()">disconnect</A> and re<A HREF="#connect()">connect</A>, you'll be reconnecting to the database using the <I>same</I> user/pass/JDBC characteristics as provided to the constructor of <I>this</I> class.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class DBConnection extends DBConnDirect  {

   private String sUsername = null;
   private String sPassword = null;
   private String sJdbcConnectionString = null;
   private String sJdbcDriver = null;

   /**
      <P>Create a DBConnection.</P>

      @param  s_verificationSelect  Passed directly to the <A HREF="~JD~dbcd#dbcd(s,optr)~EJD~">two-parameter constructor</A> of <A HREF="DBConnDirect.html">DBConnDirect</A>.
      @param  All other params passed directly to <A HREF="~JD~connect(s,s,s,s)~EJD~">connect</A>
    **/
   public DBConnection(String s_username, String s_password, String s_jdbcConnectionString, String s_jdbcDriver, String s_verificationSelect) throws SQLException, ClassNotFoundException  {
      super(s_verificationSelect);
      connect(s_username, s_password, s_jdbcConnectionString, s_jdbcDriver);
   }


   /**
      <P>Create a DBConnection.</P>

      <P>This immediately attempts to <A HREF="#connect()">connect</A> to the database.</P>

      @param  s_verificationSelect  Passed directly to the <A HREF="~JD~dbcd#dbcd(s,optr)~EJD~">two-parameter constructor</A> of <A HREF="DBConnDirect.html">DBConnDirect</A>.
      @param  optr_dbg  Passed directly to the two-parameter constructor of DBConnDirect.
      @param  All other params passed directly to <A HREF="~JD~connect(s,s,s,s)~EJD~">connect</A>
    **/
   public DBConnection(String s_username, String s_password, String s_jdbcConnectionString, String s_jdbcDriver, String s_verificationSelect, Outputter optr_dbg) throws SQLException, ClassNotFoundException  {
      super(s_verificationSelect, optr_dbg);
      connect(s_username, s_password, s_jdbcConnectionString, s_jdbcDriver);
   }

   /**
      <P>Connect to the database, if not already connected.  You may <A HREF="DBConnDirect.html#disconnect()">disconnect</A> and connect repeatedly, although it is process and resource-intensive.</P>

      @exception  AssertException  If <A HREF="DBConnDirect.html#isConnected()">isConnected</A> is true.
      @exception  SQLException  If anything database related goes wrong, such as an incorrect username/password combination.
      @exception  ClassNotFoundException  If anything is inaccurate with the JDBC driver as you provided into the <A HREF="~JD~dbc(s,s,s,s,s,optr)~EJD~">constructor</A>.
    **/
   public final void connect() throws SQLException, ClassNotFoundException  {

      if(isConnected())  {
         throwAX("connect:  Already connected.  Try disconnect().");
      }

      dbg("Class.forName('" + getJdbcDriver() + "')...");

      try  {
         Class.forName(getJdbcDriver());
      }  catch(IllegalArgumentException iax)  {
         throwAX("connect:  Attempting to register the JDBC driver with Class.forName('" + getJdbcDriver() + "').  " + iax.toString());
      }  catch(ClassNotFoundException cnfx)  {
         String sError = "Attempting to register the JDBC driver with Class.forName('" + getJdbcDriver() + "').  " + cnfx.toString();
         dbg("connect:  " + sError);
         throw new ClassNotFoundException("ERROR in DBConection.connect:  " + sError);
      }

      dbg("Connecting...");
      dbg("\tgetJdbcConnectionString()='" + getJdbcConnectionString() + "'");
      dbg("\tgetDatabaseUsername()='" + getDatabaseUsername() + "'");

      try  {
         Connection conn = DriverManager.getConnection(getJdbcConnectionString(), getDatabaseUsername(), sPassword);
         setConnection(conn);
      }  catch(SQLException sqlx)  {
         throwSQLX("DBConnection.connect:  Cannot create the connection to the database, via 'DriverManager.getConnection(connect_string='" + getJdbcConnectionString() + "', username='" + getDatabaseUsername() + "', password=[HIDDEN]).  " + sqlx.toString());
      }

      dbg("conn.prepareStatement('" + getVerificationSelect() + "')...");

      prepareVerificationSelect("connect");

      dbg("...SUCCESS.  Connected.");
   }

   /**
      <P>Get the database username.</P>

      @return  <B>s_username</B> exactly as provided to the <A HREF="~JD~dbc(s,s,s,s,s,optr)~EJD~">constructor</A>.
    **/
   public synchronized String getDatabaseUsername()  {
      return sUsername;
   }

   /**
      <P>Get the database user's password...</P>

      <P>Just kidding.  It only returns null.</P>
    **/
   public synchronized String getDatabasePassword()  {
      return null;
   }

   /**
      <P>Get the JDBC driver string.</P>

      @return  <B>s_jdbcDriver</B> exactly as provided to the <A HREF="~JD~dbc(s,s,s,s,s,optr)~EJD~">constructor</A>.
   **/
   public synchronized String getJdbcDriver()  {
      return sJdbcDriver;
   }

   /**
      <P>Get the JDBC connection string.</P>

      @return  <B>s_jdbcConnectionString</B> exactly as provided to the <A HREF="~JD~dbc(s,s,s,s,s,optr)~EJD~">constructor</A>.
    **/
   public synchronized String getJdbcConnectionString()  {
      return sJdbcConnectionString;
   }


   /**
      <P>Get some information about this DBConnection.</P>
    **/
   public String toString()  {
      return super.toString() + ", getDatabaseUsername()=" + getDatabaseUsername() + ", getJdbcDriver()=" + getJdbcDriver() + ", getJdbcConnectionString()=" + getJdbcConnectionString();
   }


   /**
      <P>Connect to the database.</P>

      <P>If currently <A HREF="DBConnDirect.html#isConnected()">connected</A>, then <A HREF="DBConnDirect.html#disconnect()">disconnect</A>.</P>

      @param  s_username  Database username.  If non-null, may not be zero characters in length.
      @param  s_password  Database password associated to s_username.  If non-null, may not be zero characters in length.
      @param  s_jdbcConnectionString  JDBC connection string.  May not be null or zero characters in length.  For example: <CODE>jdbc:oracle:thin:@horizon.wharton.upenn.edu:1521:dev"</CODE>.  Your database administrator will be able to help you determine what this (parts of it, anyway) needs to be.
      @param  s_jdbcDriver  JDBC driver.  May not be null or zero characters in length.  For example:  <CODE>"oracle.jdbc.driver.OracleDriver"</CODE>
    **/
   public void connect(String s_username, String s_password, String s_jdbcConnectionString, String s_jdbcDriver) throws SQLException, ClassNotFoundException  {
      if(isConnected())  {
         disconnect();
      }

      if((s_username != null  &&  s_username.length() < 1)  ||
            (s_password != null  &&  s_password.length() < 1)  ||
             s_jdbcConnectionString == null  ||  s_jdbcConnectionString.length() < 1  ||
             s_jdbcDriver == null  ||  s_jdbcDriver.length() < 1)  {
         throwAX("constructor:  All string parameters must be non-null and at least one chararacter in length.");
      }

      sUsername = s_username;
      sPassword = s_password;
      sJdbcConnectionString = s_jdbcConnectionString;
      sJdbcDriver = s_jdbcDriver;

      connect();
   }

}