Connection Class

Used to open and close a connection to a database and execute queries.

Constructors

Connection( )
Connection( java.sql.Connection conn )

Public Methods

isOpen( ) returns boolean
Returns true if the connection is open.
isClosed( ) returns boolean
Returns true if the connection is closed.
getConnectionSpeed( ) returns long
Used to retrieve the time it took to open the database connection (in milliseconds)
getConnection( ) returns java.sql.Connection
Used to retrieve the java.sql.Connection for this Connection
open( String ConnectionString ) returns boolean
Used to open a connection to the database using a JDBC connection string. Returns true if the connection was opened successfully.
ConnectionStringA jdbc connection string/url. All connection URLs have the following form:
 jdbc:[dbVendor]://[dbName][propertyList] 
Example:
 jdbc:derby://temp/my.db;user=admin;password=mypassword 
open( Database database ) returns boolean
Used to open a connection to the database using a javaxt.sql.Database. Returns true if the connection was opened successfully.
open( java.sql.Connection conn, Database database ) returns boolean
Used establish a connection to the database using a previously opened java.sql.Connection. Returns true if the connection is open.
connAn open java.sql.Connection
databaseUsed to associate a database instance with this connection. In doing so, you can avoid a potentially costly call parse connection metadata.
open( java.sql.Connection conn ) returns boolean
Used establish a connection to the database using a previously opened java.sql.Connection. Returns true if the connection is open.
close( ) returns void
Used to close a connection to the database, freeing up server resources. It is imperative that the database connection is closed after it is no longer needed, especially if the connection came from a ConnectionPool. That said, this class implements the AutoCloseable interface so you do not have to call this method if the connection was opened as part of a "try" statement. Example:
    try (javaxt.sql.Connection conn = database.getConnection()){

    }
    catch(Exception e){
        e.printStackTrace();
    }    
getRecords( String sql ) returns Iterable<javaxt.sql.Record>
Used to execute a SQL statement and returns Records as an iterator. Example:
    for (javaxt.sql.Record record : conn.getRecords("select id from contacts")){
        System.out.println(record.get(0));
    }    
Note that records returned by this method are read-only.
getRecords( String sql, Map<String, Object> props ) returns Iterable<javaxt.sql.Record>
Used to execute a SQL statement and returns a Records as an iterator. Example:
    for (javaxt.sql.Record record : conn.getRecords(

        "select first_name, last_name from contacts",

        new HashMap<String, Object>() {{
            put("readOnly", true);
            put("fetchSize", 1000);
        }}
    ))
    {
        System.out.println(record.get("first_name") + " " + record.get("last_name"));
    }    
sqlQuery statement. This parameter is required.
propsRecordset options (e.g. readOnly, fetchSize, batchSize). See the Recordset class for more information about this properties. This parameter is optional.
getRecord( String sql ) returns javaxt.sql.Record
Returns a single record from the database. Example:
    javaxt.sql.Record record = conn.getRecord("select count(*) from contacts");
    if (record!=null) System.out.println(record.get(0));    
Note that records returned by this method are read-only.
getRecordset( String sql, Map<String, Object> props ) returns Recordset
Used to execute a SQL statement and return an open Recordset. The caller must explicitly close the Recordset when finished or invoke the getRecordset() method it in a try/catch statement.
sqlQuery statement. This parameter is required.
propsRecordset options (e.g. readOnly, fetchSize, batchSize). See the getRecords() method for an example of how to set properties. This parameter is optional.
getRecordset( String sql, boolean readOnly ) returns Recordset
Used to execute a SQL statement and return an open Recordset. The caller must explicitly close the Recordset when finished or invoke the getRecordset() method it in a try/catch statement. Example usage:
    try (javaxt.sql.Connection conn = db.getConnection()){

      //Open recordset
        try (javaxt.sql.Recordset rs = conn.getRecordset("select * from contacts")){

          //Iterate through the records
            while (rs.next()){

              //Do something with the record. Example:
                System.out.println(rs.getValue(0));
            }

        }
    }
    catch(Exception e){
        e.printStackTrace();
    }    
sqlQuery statement. This parameter is required.
readOnlyIf true, will
getRecordset( String sql ) returns Recordset
Used to execute a SQL statement and return an open Recordset. The caller must explicitly close the Recordset when finished or invoke the getRecordset() method it in a try/catch statement. See the other getRecordset() for an example. Note that records returned by this method are read-only.
execute( String sql ) returns void
Used to execute a prepared sql statement (e.g. "delete from my_table").
commit( ) returns void
Used to explicitly commit changes made to the database.
getDatabase( ) returns Database
Used to return database information associated with this connection.