net.sourceforge.orbroker
Class Broker

java.lang.Object
  net.sourceforge.orbroker.Broker

public final class Broker

extends Object

The Broker between the JDBC data source and an application. The Broker holds the configuration and initiates Queries and Transactions.

Version:

2.0

Author:

Nils Kilden-Pedersen

See Also:

Query, Transaction

Constructor Summary

Broker(DataSource dataSource)
Create Broker without a configuration.

Broker(DataSource dataSource, String username, String password)
Create Broker without a configuration.

Broker(InputStream configuration, DataSource dataSource)
The Broker is configured by passing an InputStream containing an XML file and a data source.

Broker(InputStream configuration, DataSource dataSource, String username, String password)
The Broker is configured by passing an InputStream containing an XML file and a data source with username and password.

Method Summary

static void	addLoggingHandler(Handler handler) Add logging handler.
static void	addLoggingHandler(Handler handler, boolean keepDefaultHandler) Add logging handler.
void	addStatement(String id, String sql) Add statement to Broker.
void	addStatement(String id, String sql, String resultObjectId) Add statement to Broker.
DataSource	getDataSource() Get the data source used by Broker.
String	getName() Get brokerName of Broker.
static void	log(Level level, String message) Log a message.
Executable	obtainExecutable(Connection connection) Obtain an Executable.
void	releaseExecutable(Executable executable) Release Executable.
void	setCatalog(String catalog) Set the catalog.
void	setDataSource(DataSource dataSource) Set the data source.
void	setDataSource(DataSource dataSource, String username, String password) Set data source and username/password.
void	setExceptionEvaluator(ExceptionEvaluator evaluator) Set a new exception evaluator.
static void	setLoggingLevel(Level level) Set the logging level.
static void	setLoggingLevel(String level) Set the logging level.
void	setTextReplacement(String key, String value) Set a text replacement value.
void	setTextReplacements(Properties textReplacements) Set text replacement values.
Query	startQuery() Start a read-only query.
Query	startQuery(int isolationLevel) Start a read-only query with a given transaction isolation level.
Transaction	startTransaction() Start a new transaction.
Transaction	startTransaction(int isolationLevel) Start a new transaction with a given transaction isolation level.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Broker

public Broker(DataSource dataSource)

Create Broker without a configuration.

Parameters:

dataSource - A data source

See Also:

addStatement(String, String)

Broker

public Broker(DataSource dataSource,
              String username,
              String password)

Create Broker without a configuration.

Parameters:

dataSource - A data source

username - Username to use that is different than on data source

password - Password for username

See Also:

addStatement(String, String)

Broker

public Broker(InputStream configuration,
              DataSource dataSource)
       throws BrokerException

The Broker is configured by passing an InputStream containing an XML file and a data source.

Parameters:

configuration - The XML configuration

dataSource - A data source

Throws:

BrokerException

Broker

public Broker(InputStream configuration,
              DataSource dataSource,
              String username,
              String password)
       throws BrokerException

The Broker is configured by passing an InputStream containing an XML file and a data source with username and password.

Parameters:

configuration - The XML configuration

dataSource - A data source

username - Username to use that is different than on data source

password - Password for username

Throws:

BrokerException

Method Detail

addLoggingHandler

public static void addLoggingHandler(Handler handler)

Add logging handler. When adding a logging handler, the default console log handler is automatically removed. Previously added handlers remain.

Parameters:

handler - Logging handler.

See Also:

Handler, addLoggingHandler(Handler, boolean)

addLoggingHandler

public static void addLoggingHandler(Handler handler,
                                     boolean keepDefaultHandler)

Add logging handler. Previously added handlers remain.

Parameters:

handler - Logging handler.

keepDefaultHandler - true, if default console log handler should remain

See Also:

Handler, addLoggingHandler(Handler)

log

public static void log(Level level,
                       String message)

Log a message.

Parameters:

level - Log level

message - Log message

setLoggingLevel

public static void setLoggingLevel(Level level)

Set the logging level. Log level definitions:

• WARNING: Used for internally caught exceptions not considered severe.
• INFO: Shows transaction boundaries and SQL statements executed.
• CONFIG: Information about driver support and configuration setup
• FINE: Shows dynamic SQL statement after parsing.

Parameters:

level - Logging level

setLoggingLevel

public static void setLoggingLevel(String level)

Set the logging level. See log level definitions on setLoggingLevel(Level).

Parameters:

level - Logging level

See Also:

Level

addStatement

public void addStatement(String id,
                         String sql)
                  throws BrokerException,
                         ConfigurationException

Add statement to Broker.

Parameters:

id - The statement id.

sql - The SQL statement

Throws:

BrokerException

ConfigurationException

addStatement

public void addStatement(String id,
                         String sql,
                         String resultObjectId)
                  throws BrokerException,
                         ConfigurationException

Add statement to Broker.

Parameters:

id - The statement id.

sql - The SQL statement

resultObjectId - The result-object id as defined in the XML configuration file.

Throws:

BrokerException

ConfigurationException

getDataSource

public DataSource getDataSource()

Get the data source used by Broker.

Returns:

The datasource used.

getName

public String getName()

Get brokerName of Broker.

Returns:

Name of broker

obtainExecutable

public Executable obtainExecutable(Connection connection)

Obtain an Executable. An Executable instance must be released again by calling releaseExecutable(Executable), or unpredictable behavior can occur.

Parameters:

connection - An externally managed connection.

Returns:

Executable

See Also:

releaseExecutable(Executable), Transaction.obtainExecutable()

releaseExecutable

public void releaseExecutable(Executable executable)

Release Executable. This will drop the internal Connection and prevent other processes, which may hold a reference to the Executable, from executing statements on a Connection that may have been returned to a DataSource connection pool.

Releasing the Executable will not close the connection.

Parameters:

executable - The Executable to release

Throws:

BrokerException - if the Executable was not obtained from this Broker

See Also:

obtainExecutable(Connection)

setCatalog

public void setCatalog(String catalog)

Set the catalog.

Parameters:

catalog - The catalog name

setDataSource

public void setDataSource(DataSource dataSource)

Set the data source. Uses default username and password.

Parameters:

dataSource - The data source

setDataSource

public void setDataSource(DataSource dataSource,
                          String username,
                          String password)

Set data source and username/password.

Parameters:

dataSource - The data source

username - Username to use that is different than on data source

password - Password for username

setExceptionEvaluator

public void setExceptionEvaluator(ExceptionEvaluator evaluator)

Set a new exception evaluator.

Parameters:

evaluator - The exception evaluator instance

setTextReplacement

public void setTextReplacement(String key,
                               String value)

Set a text replacement value. This will replace a {{key}} string with the specific parameter value.

Parameters:

key - Text replacement key

value - Text replacement value

See Also:

setTextReplacements(Properties)

setTextReplacements

public void setTextReplacements(Properties textReplacements)

Set text replacement values. This will replace all {{key}} type properties in an sql-statement with the values.

Parameters:

textReplacements - The replacement values to set.

See Also:

setTextReplacement(String, String)

startQuery

public Query startQuery()

Start a read-only query.

Returns:

Query

startQuery

public Query startQuery(int isolationLevel)

Start a read-only query with a given transaction isolation level. JDBC transaction isolation levels:

• Connection.TRANSACTION_NONE
• Connection.TRANSACTION_READ_UNCOMMITTED
• Connection.TRANSACTION_READ_COMMITTED
• Connection.TRANSACTION_REPEATABLE_READ
• Connection.TRANSACTION_SERIALIZABLE

Parameters:

isolationLevel - The isolation level

Returns:

Query

startTransaction

public Transaction startTransaction()
                             throws BrokerException

Start a new transaction.

Returns:

Transaction

Throws:

BrokerException

startTransaction

public Transaction startTransaction(int isolationLevel)
                             throws BrokerException

Start a new transaction with a given transaction isolation level. JDBC transaction isolation levels:

• Connection.TRANSACTION_NONE
• Connection.TRANSACTION_READ_UNCOMMITTED
• Connection.TRANSACTION_READ_COMMITTED
• Connection.TRANSACTION_REPEATABLE_READ
• Connection.TRANSACTION_SERIALIZABLE

Parameters:

isolationLevel - The isolation level

Returns:

Transaction

Throws:

BrokerException

toString

public String toString()

See Also:

Object.toString()