org.javalite.activejdbc
Class DB

java.lang.Object
  org.javalite.activejdbc.DB

public class DB
extends Object

This class provides a number of convenience methods for opening/closing database connections, running various types of queries, and executing SQL statements. This class differs from Base such that in this class you can provide a logical name for a current connection. Use this class when you have more than one database in the system.

Author:

Igor Polevoy

Constructor Summary

DB(String dbName)
Creates a new DB object representing a connection to a DB.

Method Summary

void	close() Closes connection.
static void	closeAllConnections() Closes all current connections.
void	commitTransaction() Commits local transaction.
Connection	connection() Provides connection from current thread.
static Map<String,Connection>	connections() Provides connections available on current thread.
Long	count(String table) Returns count of rows in table.
Long	count(String table, String query, Object... params) Runs a count query, returns a number of matching records.
int	exec(String query) Executes DML.
int	exec(String query, Object... params) Executes parametrized DML - will contain question marks as placeholders.
RowProcessor	find(String query, Object... params) Executes a raw query and returns an instance of RowProcessor.
void	find(String sql, RowListener listener) Executes a raw query and calls instance of RowListener with every row found.
List<Map>	findAll(String query) This method returns entire resultset as one list.
List<Map>	findAll(String query, Object... params) This method returns entire resultset as one list.
Object	firstCell(String query, Object... params) This method returns a value of the first column of the first row.
List	firstColumn(String query, Object... params) This method returns entire resultset as one list.
Connection	getConnection() Synonym of connection() for people who like getters.
static List<String>	getCurrrentConnectionNames() Provides a names' list of current connections.
boolean	hasConnection() Use to check if there is a connection present on current thread.
void	open(ConnectionSpec spec) This method is used internally by framework.
void	open(DataSource datasource) Opens a connection from a datasource.
void	open(String jndiName) Opens a connection from JNDI based on a registered name.
void	open(String jndiName, Properties jndiProperties) Opens a new connection from JNDI data source by name using explicit JNDI properties.
void	open(String driver, String url, Properties props) Opens a new connection in case additional driver-specific parameters need to be passed in.
void	open(String driver, String url, String user, String password) Opens a new connection based on JDBC properties and attaches it to a current thread.
void	openTransaction() Opens local transaction.
void	rollbackTransaction() Rolls back local transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DB

public DB(String dbName)

Creates a new DB object representing a connection to a DB.

Parameters:

dbName - logical name for a database.

Method Detail

open

public void open(String driver,
                 String url,
                 String user,
                 String password)

Opens a new connection based on JDBC properties and attaches it to a current thread.

Parameters:

driver - class name of driver

url - URL connection to DB

user - user name.

password - password.

open

public void open(String driver,
                 String url,
                 Properties props)

Opens a new connection in case additional driver-specific parameters need to be passed in.

Parameters:

driver - driver class name

url - JDBC URL

props - connection properties

open

public void open(String jndiName)

Opens a connection from JNDI based on a registered name. This assumes that there is a jndi.properties file with proper JNDI configuration in it.

Parameters:

jndiName - name of a configured data source.

open

public void open(DataSource datasource)

Opens a connection from a datasource. This methods gives a high level control while sourcing a DB connection.

Parameters:

datasource - datasource will be used to acquire a connection.

open

public void open(String jndiName,
                 Properties jndiProperties)

Opens a new connection from JNDI data source by name using explicit JNDI properties. This method can be used in cases when file jndi.properties cannot be easily updated.

Parameters:

jndiName - name of JNDI data source.

jndiProperties - JNDI properties

open

public void open(ConnectionSpec spec)

This method is used internally by framework.

Parameters:

spec - specification for a JDBC connection.

close

public void close()

Closes connection.

count

public Long count(String table)

Returns count of rows in table.

Parameters:

table - name of table.

Returns:

count of rows in table.

count

public Long count(String table,
                  String query,
                  Object... params)

Runs a count query, returns a number of matching records.

Parameters:

table - table in which to count rows.

query - this is a filtering query for the count. If '*' provided, all records will be counted. Example: "age > 65 AND department = 'accounting'"

params - parameters for placeholder substitution.

Returns:

count number of records found in a table.

firstCell

public Object firstCell(String query,
                        Object... params)

This method returns a value of the first column of the first row. This query expects only one column selected in the select statement. If more than one column returned, it will throw IllegalArgumentException.

Parameters:

query - query

params - parameters

Returns:

fetched value, or null if query did not fetch anything.

findAll

public List<Map> findAll(String query,
                         Object... params)

This method returns entire resultset as one list. Do not use it for large result sets. Example:

 
 List> people = Base.findAll("select * from people where first_name = ?", "John");
  for(Map person: people)
      System.out.println(person.get("first_name"));
 
 

Parameters:

query - raw SQL query. This query is parametrized.

params - list of parameters for a parametrized query.

Returns:

entire result set corresponding to the query.

firstColumn

public List firstColumn(String query,
                        Object... params)

This method returns entire resultset as one list. Do not use it for large result sets. Example:

  List ssns = Base.firstColumn("select ssn from people where first_name = ?", "John");
  for(Object ssn: ssns)
      System.out.println(ssn);
 

This methods expects a query which selects only one column from a table/view. It will throw an exception if more than one columns are fetched in a result set.

Parameters:

query - raw SQL query. This query is parametrized.

params - list of parameters for a parametrized query.

Returns:

entire result set corresponding to the query.

findAll

public List<Map> findAll(String query)

This method returns entire resultset as one list. Do not use it for large result sets.

Parameters:

query - raw SQL query. This query is not parametrized.

Returns:

entire result set corresponding to the query.

find

public RowProcessor find(String query,
                         Object... params)

Executes a raw query and returns an instance of RowProcessor. Use it in the following pattern:

 Base.find("select first_name, last_name from really_large_table").with(new RowListenerAdapter() {
            public void onNext(Map row) {
                ///write your code here
                Object o1 = row.get("first_name");
                Object o2 = row.get("last_name");
            }
        });
     

Parameters:

query - raw SQL.

params - list of parameters if query is parametrized.

Returns:

instance of RowProcessor which has with() method for convenience.

find

public void find(String sql,
                 RowListener listener)

Executes a raw query and calls instance of RowListener with every row found. Use this method for very large result sets.

Parameters:

sql - raw SQL query.

listener - client listener implementation for processing individual rows.

exec

public int exec(String query)

Executes DML. Use it for inserts and updates.

Parameters:

query - raw DML.

Returns:

number of rows afected by query.

exec

public int exec(String query,
                Object... params)

Executes parametrized DML - will contain question marks as placeholders.

Parameters:

query - query to execute - will contain question marks as placeholders.

params - query parameters.

Returns:

number of records affected.

openTransaction

public void openTransaction()

Opens local transaction.

commitTransaction

public void commitTransaction()

Commits local transaction.

rollbackTransaction

public void rollbackTransaction()

Rolls back local transaction.

connection

public Connection connection()

Provides connection from current thread.

Returns:

connection from current thread.

hasConnection

public boolean hasConnection()

Use to check if there is a connection present on current thread.

Returns:

true if finds connection on current thread, false if not.

getConnection

public Connection getConnection()

Synonym of connection() for people who like getters.

Returns:

connection from current thread.

getCurrrentConnectionNames

public static List<String> getCurrrentConnectionNames()

Provides a names' list of current connections.

Returns:

a names' list of current connections.

closeAllConnections

public static void closeAllConnections()

Closes all current connections.

connections

public static Map<String,Connection> connections()

Provides connections available on current thread.

Returns:

connections available on current thread.