Examine individual changes

'{{Infobox_Software |name = Java Database Connectivity |logo = |caption = |developer = |latest_release_version = |latest_release_date = |latest preview version = |latest preview date = |operating_system = |genre = Data Access API |license = |website = {{Javadoc:SE-guide|jdbc|JDBC API Guide}} }} '''Java DataBase Connectivity''', commonly referred to as '''JDBC''', is an [[Application programming interface|API]] for the [[Java (programming language)|Java programming language]] that defines how a client may access a [[database]]. It provides methods for querying and updating data in a database. JDBC is oriented towards [[Relational database management system|relational databases]]. A JDBC-to-[[Open Database Connectivity|ODBC]] bridge enables connections to any ODBC-accessible data source in the JVM host environment. ==History and implementation== [[Sun Microsystems]] released JDBC as part of [[Java Development Kit | JDK]] 1.1 on February 19, 1997.<ref> {{cite web | url = http://web.archive.org/web/20080210044125/http://www.sun.com/smi/Press/sunflash/1997-02/sunflash.970219.0001.xml | title = SUN SHIPS JDK 1.1 -- JAVABEANS INCLUDED | date = 1997-02-19 | work = www.sun.com | publisher = [[Sun Microsystems]] | archiveurl = | archivedate = | accessdate = 2010-02-15 | quote = February 19, 1997 - The JDK 1.1 [...] is now available [...]. This release of the JDK includes: [...] Robust new features including JDBC[tm] for database connectivity }} </ref> It has since formed part of the [[Java Platform, Standard Edition | Java Standard Edition]]. The JDBC classes are contained in the [[Java package]] {{Javadoc:SE|package=java.sql|java/sql}} and {{Javadoc:SE|package=javax.sql|javax/sql}}. Starting with version 3.0 , JDBC has been developed under the [[Java Community Process]]. JSR 54 specifies JDBC 3.0 (included in J2SE 1.4), JSR 114 specifies the JDBC Rowset additions, and JSR 221 is the specification of JDBC 4.0 (included in Java SE 6).<ref>[http://java.sun.com/products/jdbc/download.html#corespec40 JDBC API Specification Version: 4.0]</ref> ==Functionality== JDBC allows multiple implementations to exist and be used by the same application. The API provides a mechanism for dynamically loading the correct Java packages and registering them with the JDBC Driver Manager. The Driver Manager is used as a connection factory for creating JDBC connections. JDBC connections support creating and executing statements. These may be update statements such as [[SQL]]'s CREATE, INSERT, UPDATE and DELETE, or they may be query statements such as SELECT. Additionally, [[stored procedures]] may be invoked through a JDBC connection. JDBC represents statements using one of the following classes: * {{Javadoc:SE|java/sql|Statement}} &ndash; the statement is sent to the database server each and every time. * {{Javadoc:SE|java/sql|PreparedStatement}} &ndash; the statement is cached and then the execution path is pre determined on the database server allowing it to be executed multiple times in an efficient manner. * {{Javadoc:SE|java/sql|CallableStatement}} &ndash; used for executing [[stored procedures]] on the database. Update statements such as INSERT, UPDATE and DELETE return an update count that indicates how many rows were affected in the database. These statements do not return any other information. Query statements return a JDBC row result set. The row result set is used to walk over the result set. Individual columns in a row are retrieved either by name or by column number. There may be any number of rows in the result set. The row result set has metadata that describes the names of the columns and their types. There is an extension to the basic JDBC API in the {{Javadoc:SE|package=javax.sql|javax/sql}}. JDBC connections are often managed via a connection pool rather than obtained directly from the driver. Examples of connection pools include [http://jolbox.com BoneCP], [http://sourceforge.net/projects/c3p0 C3P0] and [http://commons.apache.org/dbcp DBCP] ==Getting Started with JDBC<ref>Jeffery D. Ullman, J. W. (2008). A first course in Database Systems. Pearson.</ref>== 1. Make the JDBC classes available to your Java program using: : import java.sql.*; 2. Load the driver for the database system using: : Class.forName(<driverName>); 3. Establish a connection to the database using : : Connection con= DriverManage.getConnection(<url>,<user>,<password>); Now we have a connection object called con which we can use to create statements. There are 2 methods to create statements: : a) createStatement() returns a Statement object : b) prepareStatement(Q) where Q is a SQL query passed as a string argument, returns a preparedStatement object There are 4 methods that execute SQL statements. : a) executeQuery(Q) takes a statement Q and is applied to a Statement object. This method returns a ResultSet object, which is the set of tuples produced by the query Q : b) executeQuery() is applied to a preparedStatement object. This method also returns a ResultSet object. : c) excuteUpdate(U) takes a nonquery statement U and, when applied to a statement object, executes U. : d) executeUpdate() is applied to a preparedStatement object. The SQL statement associated with the prepared statement is executed. ==Examples== The method {{Javadoc:SE|member=forName(String)|java/lang|Class|forName(java.lang.String)}} is used to load the JDBC driver class. The line below causes the JDBC driver from ''some jdbc vendor'' to be loaded into the application. (Some JVMs also require the class to be instantiated with {{Javadoc:SE|name=.newInstance()|java/lang|Class|newInstance()}}.) <source lang=java5> Class.forName( "com.somejdbcvendor.TheirJdbcDriver" ); </source> In JDBC 4.0, it's no longer necessary to explicitly load JDBC drivers using Class.forName(). See [http://www.onjava.com/pub/a/onjava/2006/08/02/jjdbc-4-enhancements-in-java-se-6.html JDBC 4.0 Enhancements in Java SE 6]. When a {{Javadoc:SE|java/sql|Driver}} class is loaded, it creates an instance of itself and registers it with the {{Javadoc:SE|java/sql|DriverManager}}. This can be done by including the needed code in the driver class's <code>static</code> block. e.g. <code>DriverManager.registerDriver(Driver driver)</code> Now when a connection is needed, one of the <code>DriverManager.getConnection()</code> methods is used to create a JDBC connection. <source lang=java5> Connection conn = DriverManager.getConnection( "jdbc:somejdbcvendor:other data needed by some jdbc vendor", "myLogin", "myPassword" ); try { /* you use the connection here */ } finally { //It's important to close the connection when you are done with it try { conn.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } </source> The URL used is dependent upon the particular JDBC driver. It will always begin with the "jdbc:" protocol, but the rest is up to the particular vendor. Once a connection is established, a statement must be created. <source lang=java5> Statement stmt = conn.createStatement(); try { stmt.executeUpdate( "INSERT INTO MyTable( name ) VALUES ( 'my name' ) " ); } finally { //It's important to close the statement when you are done with it try { stmt.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } </source> Note that Connections, Statements, and ResultSets often tie up [[operating system]] resources such as sockets or file descriptors. In the case of Connections to remote database servers, further resources are tied up on the server, e.g., cursors for currently open ResultSets. It is vital to <code>close()</code> any JDBC object as soon as it has played its part; garbage collection should not be relied upon. Forgetting to <code>close()</code> things properly results in spurious errors and misbehaviour. The above try-finally construct is a recommended code pattern to use with JDBC objects. Data is retrieved from the database using a database query mechanism. The example below shows creating a statement and executing a query. <source lang=java5> Statement stmt = conn.createStatement(); try { ResultSet rs = stmt.executeQuery( "SELECT * FROM MyTable" ); try { while ( rs.next() ) { int numColumns = rs.getMetaData().getColumnCount(); for ( int i = 1 ; i <= numColumns ; i++ ) { // Column numbers start at 1. // Also there are many methods on the result set to return // the column as a particular type. Refer to the Sun documentation // for the list of valid conversions. System.out.println( "COLUMN " + i + " = " + rs.getObject(i) ); } } } finally { try { rs.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } } finally { try { stmt.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } </source> Typically, however, it would be rare for a seasoned Java programmer to code in such a fashion. The usual practice would be to abstract the database logic into an entirely different class and to pass preprocessed strings (perhaps derived themselves from a further abstracted class) containing SQL statements and the connection to the required methods. Abstracting the data model from the application code makes it more likely that changes to the application and data model can be made independently. An example of a <code>PreparedStatement</code> query, using <code>conn</code> and class from first example. <source lang=java5> PreparedStatement ps = conn.prepareStatement( "SELECT i.*, j.* FROM Omega i, Zappa j WHERE i.name = ? AND j.num = ?" ); try { // In the SQL statement being prepared, each question mark is a placeholder // that must be replaced with a value you provide through a "set" method invocation. // The following two method calls replace the two placeholders; the first is // replaced by a string value, and the second by an integer value. ps.setString(1, "Poor Yorick"); ps.setInt(2, 8008); // The ResultSet, rs, conveys the result of executing the SQL statement. // Each time you call rs.next(), an internal row pointer, or cursor, // is advanced to the next row of the result. The cursor initially is // positioned before the first row. ResultSet rs = ps.executeQuery(); try { while ( rs.next() ) { int numColumns = rs.getMetaData().getColumnCount(); for ( int i = 1 ; i <= numColumns ; i++ ) { // Column numbers start at 1. // Also there are many methods on the result set to return // the column as a particular type. Refer to the Sun documentation // for the list of valid conversions. System.out.println( "COLUMN " + i + " = " + rs.getObject(i) ); } // for } // while } finally { try { rs.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } } finally { try { ps.close(); } catch (Throwable ignore) { /* Propagate the original exception instead of this one that you may want just logged */ } } // try </source> If a database operation fails, JDBC raises an {{Javadoc:SE|java/sql|SQLException}}. There is typically very little one can do to recover from such an error, apart from logging it with as much detail as possible. It is recommended that the SQLException be translated into an application ___domain exception (an unchecked one) that eventually results in a transaction rollback and a notification to the user. An example of a [[database transaction]]: <source lang=java5> boolean autoCommitDefault = conn.getAutoCommit(); try { conn.setAutoCommit(false); /* You execute statements against conn here transactionally */ conn.commit(); } catch (Throwable e) { try { conn.rollback(); } catch (Throwable ignore) {} throw e; } finally { try { conn.setAutoCommit(autoCommitDefault); } catch (Throwable ignore) {} } </source> '''Here are examples of host database types which Java can convert to with a function'''. {| class="wikitable" |+ <code>setXXX()</code> Methods |- ! Oracle Datatype ! <code>setXXX()</code> |- | CHAR | <code>setString()</code> |- | VARCHAR2 | <code>setString()</code> |- |rowspan="8"| NUMBER | <code>setBigDecimal()</code> |- | <code>setBoolean()</code> |- | <code>setByte()</code> |- | <code>setShort()</code> |- | <code>setInt()</code> |- | <code>setLong()</code> |- | <code>setFloat()</code> |- | <code>setDouble()</code> |- | INTEGER | <code>setInt()</code> |- | FLOAT | <code>setDouble()</code> |- | CLOB | <code>setClob()</code> |- | BLOB | <code>setBlob()</code> |- | RAW | <code>setBytes()</code> |- | LONGRAW | <code>setBytes()</code> |- |rowspan="3"| DATE | <code>setDate()</code> |- | <code>setTime()</code> |- | <code>setTimestamp()</code> |} For an example of a <code>CallableStatement</code> (to call stored procedures in the database), see the {{Javadoc:SE-guide|jdbc/getstart/callablestatement.html|JDBC API Guide}}. ===Bad Examples=== The Internet is full of wrong JDBC examples, even Oracle and the acquired SUN keep wrong examples where they clearly show they do not know Java has exceptions and resources must be closed in a finally clause.<ref>[http://download.oracle.com/docs/cd/E14072_01/java.112/e10589/getsta.htm Oracle® Database JDBC Developer's Guide, 11g Release 2 (11.2) 2 Getting Started]</ref><ref>[http://download.oracle.com/docs/cd/B28359_01/java.111/b31224/dbmgmnt.htm Oracle® Database JDBC Developer's Guide and Reference, 11g Release 1 (11.1) 29 Database Management]</ref><ref>[http://java.sun.com/developer/onlineTraining/Programming/JDCBook/jdbc.html SUN : Advanced Programming for the Java 2 Platform : Chapter 4: JDBC Technology]</ref> ==JDBC drivers== {{Main | JDBC driver}} JDBC drivers are client-side [[adapter]]s (installed on the client machine, not on the server) that convert requests from Java programs to a protocol that the DBMS can understand. ===Types=== There are commercial and free drivers available for most relational database servers. These drivers fall into one of the following types: * [[JDBC driver#Type 1 Driver - JDBC-ODBC bridge|Type 1]] that calls native code of the locally available ODBC driver. * [[JDBC_driver#Type 2 Driver - Native-API Driver specification|Type 2]] that calls database vendor native library on a client side. This code then talks to database over network. * [[JDBC driver#Type 3 Driver - Network-Protocol Driver|Type 3]], the pure-java driver that talks with the server-side middleware that then talks to database. * [[JDBC driver#Type 4 Driver - Native-Protocol Driver|Type 4]], the pure-java driver that uses database native protocol. There is also a type called [[internal JDBC driver]], driver embedded with JRE in Java-enabled SQL databases. It's used for [[Java stored procedure]]s. This does not belong to the above classification, although it would likely be either a type 2 or type 4 driver (depending on whether the database itself is implemented in Java or not). An example of this is the KPRB driver supplied with Oracle RDBMS. "jdbc:default:connection" is a relatively standard way of referring making such a connection (at least Oracle and Apache Derby support it). The distinction here is that the JDBC client is actually running as part of the database being accessed, so access can be made directly rather than through network protocols. ===Sources=== * SQLSummit.com publishes list of drivers, including JDBC drivers and vendors * [[Sun Microsystems]] provides a [http://developers.sun.com/product/jdbc/drivers list of some JDBC drivers and vendors] * [[Simba Technologies]] ships an SDK for building custom JDBC Drivers for any custom/proprietary relational data source * DataDirect Technologies provides a comprehensive suite of fast Type 4 JDBC drivers for all major database * IDS Software provides a Type 3 JDBC driver for concurrent access to all major databases. Supported features include resultset caching, SSL encryption, custom data source, dbShield * [[OpenLink Software]] ships JDBC Drivers for a variety of databases, including Bridges to other data access mechanisms (e.g., ODBC, JDBC) which can provide more functionality than the targeted mechanism * JDBaccess is a Java persistence library for [[MySQL]] and [[Oracle database|Oracle]] which defines major database access operations in an easy usable API above JDBC * JNetDirect provides a suite of fully Sun J2EE certified high performance JDBC drivers. * [[HSQL]] is a [[Relational database management system|RDBMS]] with a JDBC driver and is available under a BSD license. * SchemaCrawler<ref name=schemacrawler>{{cite web | author=Sualeh Fatehi | url=http://schemacrawler.sourceforge.net/ | title=SchemaCrawler | work=SourceForge }}</ref> is an open source API that leverages JDBC, and makes database metadata available as plain old Java objects (POJOs) ==References== {{reflist}} ==External links== * {{Javadoc:SE-guide|jdbc|JDBC API Guide}} Please be aware that this documentation has examples where the JDBC resources are not closed appropriately (swallowing primary exceptions and being able to cause NullPointerExceptions) and has code prone to [[SQL injection]] * {{Javadoc:SE|package=java.sql|java/sql}} API [[Javadoc]] documentation * {{Javadoc:SE|package=javax.sql|javax/sql}} API Javadoc documentation * [http://www.orbroker.org O/R Broker] Scala JDBC framework {{DEFAULTSORT:Database Connectivity}} [[Category:Java platform]] [[Category:Java specification requests]] [[Category:SQL data access]] [[Category:Databases]] [[Category:Java APIs]] [[Category:Data access technologies]] [[ar:جي دي بي سي]] [[ca:Java Database Connectivity]] [[cs:Java Database Connectivity]] [[da:JDBC]] [[de:Java Database Connectivity]] [[el:JDBC]] [[es:Java Database Connectivity]] [[fr:Java database connectivity]] [[ko:JDBC]] [[it:JDBC]] [[hu:Java Database Connectivity]] [[nl:Java DataBase Connectivity]] [[ja:JDBC]] [[no:JDBC]] [[pl:Java DataBase Connectivity]] [[pt:JDBC]] [[ru:Java Database Connectivity]] [[fi:Java Database Connectivity]] [[sv:JDBC]] [[th:JDBC]] [[uk:Java Database Connectivity]] [[vi:Java Dabase Connectivity]] [[zh:Java数据库连接]]'