com.uwyn.rife.database
Class Datasource

java.lang.Object
  com.uwyn.rife.database.Datasource

All Implemented Interfaces:

Cloneable

public class Datasource
extends Object
implements Cloneable

Contains all the information required to connect to a database and centralizes the creation of connections to a database. These connections can optionally be pooled.

The initial connection will only be made and the pool will only be initialized when a connection is obtained for the first time. The instantiation only stores the connection parameters.

A Datasource also defines the type of database that is used for all database-independent logic such as sql to java and java to sql type mappings, query builders, database-based authentication, database-based scheduling, ... The key that identifies a supported type is the class name of the jdbc driver.

A Datasource instance can be created through it's constructor, but it's recommended to work with a Datasources collection that is created and populated through XML. This can easily be achieved by using a ParticipantDatasources which participates in the application-wide repository.

Once a connection has been obtained from a pooled datasource, modifying its connection parameters is not possible anymore, a new instance has to be created to set the parameters to different values.

Since:

1.0

Version:

$Revision: 3636 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

See Also:

Datasources, Xml2Datasources, Rep, ParticipantDatasources

Constructor Summary

Datasource()
Instantiates a new Datasource object with no connection information.

Datasource(DataSource dataSource, int poolsize)
Instantiates a new Datasource object from a standard javax.sql.DataSource.

Datasource(DataSource dataSource, String driver, String user, String password, int poolsize)
Instantiates a new Datasource object from a standard javax.sql.DataSource.

Datasource(String driver, String url, String user, String password, int poolsize)
Instantiates a new Datasource object with all the connection parameters that are required.

Method Summary

void	cleanup() Cleans up all connections that have been reserved by this datasource.
Datasource	clone() Simply clones the instance with the default clone method.
boolean	equals(Object object) Indicates whether some other object is "equal to" this one.
String	getAliasedDriver() Retrieves the fully qualified class name of the jdbc driver that's used by this Datasource.
com.uwyn.rife.database.capabilities.CapabilitiesCompensator	getCapabilitiesCompensator() Retrieves a CapabilitiesCompensator instance that is able to compensate for certain missing database features
DbConnection	getConnection() Retrieves a free database connection.
DataSource	getDataSource() Retrieves the standard datasource that is used by this RIFE datasource to obtain a database connection.
String	getDriver() Retrieves the fully qualified class name of the jdbc driver that's used by this Datasource.
String	getPassword() Retrieves the password that's used by this Datasource.
ConnectionPool	getPool() Retrieves the instance of the connection pool that is provided by this dtaasource.
int	getPoolsize() Retrieves the size of the pool that's used by this Datasource.
SqlConversion	getSqlConversion() Retrieves the sql to java and java to sql type mapping logic that corresponds to the provide driver class name.
String	getUrl() Retrieves the connection url that's used by this Datasource.
String	getUser() Retrieves the user that's used by this Datasource.
int	hashCode() Returns a hash code value for the Datasource.
boolean	isPooled() Indicates whether the Datasource uses a connection pool or not
void	setDataSource(DataSource dataSource) Sets the standard datasource that will be used to connect to the database.
void	setDriver(String driver) Sets the jdbc driver that will be used to connect to the database.
void	setPassword(String password) Sets the password that will be used to connect to the database.
void	setPoolsize(int poolsize) Sets the size of the connection pool that will be used to connect to the database.
void	setUrl(String url) Sets the connection url that will be used to connect to the database.
void	setUser(String user) Sets the user that will be used to connect to the database.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Datasource

public Datasource()

Instantiates a new Datasource object with no connection information. The setters need to be used afterwards to provide each required parameter before the Datasource can be used.

Since:

1.0

See Also:

setDriver(String), setUrl(String), setUser(String), setPassword(String), setPoolsize(int), setDataSource(DataSource)

Datasource

public Datasource(String driver,
                  String url,
                  String user,
                  String password,
                  int poolsize)

Instantiates a new Datasource object with all the connection parameters that are required.

Parameters:

driver - the fully-qualified classname of the jdbc driver that will be used to connect to the database

url - the connection url which identifies the database to which the connection will be made, this is entirely driver-dependent

user - the user that will be used to connect to the database

password - the password that will be used to connect to the database

poolsize - the size of the connection pool, 0 means that the connections will not be pooled

Since:

1.0

Datasource

public Datasource(DataSource dataSource,
                  int poolsize)

Instantiates a new Datasource object from a standard javax.sql.DataSource.

The driver will be detected from the connection that is provided by this DataSource. If the driver couldn't be detected, an exception will be thrown upon connect.

Parameters:

dataSource - the standard datasource that will be used to obtain the connection

poolsize - the size of the connection pool, 0 means that the connections will not be pooled

Since:

1.3

Datasource

public Datasource(DataSource dataSource,
                  String driver,
                  String user,
                  String password,
                  int poolsize)

Instantiates a new Datasource object from a standard javax.sql.DataSource.

Parameters:

dataSource - the standard datasource that will be used to obtain the connection

driver - the fully-qualified classname of the jdbc driver that will be used to provide an identifier for the database abstraction functionalities, null will let RIFE try to figure it out by itself

user - the user that will be used to connect to the database

password - the password that will be used to connect to the database

poolsize - the size of the connection pool, 0 means that the connections will not be pooled

Since:

1.3

Method Detail

getConnection

public DbConnection getConnection()
                           throws DatabaseException

Retrieves a free database connection. If no connection pool is used, a new DbConnection will always be created, otherwise the first available connection in the pool will be returned.

Returns:

a free DbConnection instance which can be used to create an execute statements

Throws:

DatabaseException - when errors occured during the creation of a new connection or during the obtainance of a connection from the pool

Since:

1.0

getDriver

public String getDriver()

Retrieves the fully qualified class name of the jdbc driver that's used by this Datasource.

Returns:

a String with the name of the jdbc driver; or

null if the driver hasn't been set

Since:

1.0

See Also:

setDriver(String), getAliasedDriver()

getAliasedDriver

public String getAliasedDriver()

Retrieves the fully qualified class name of the jdbc driver that's used by this Datasource. Instead of straight retrieval of the internal value, it looks for jdbc driver aliases and changes the driver classname if it's not supported by RIFE, but its alias is.

Returns:

a String with the name of the jdbc driver; or

null if the driver hasn't been set

Since:

1.0

See Also:

getDriver(), setDriver(String)

setDriver

public void setDriver(String driver)

Sets the jdbc driver that will be used to connect to the database. This has to be a fully qualified class name and will be looked up through reflection. It's not possible to change the driver after a connection has been obtained from a pooled datasource.

If the class name can't be resolved, an exception is thrown during the creation of the first connection.

Parameters:

driver - a String with the fully qualified class name of the jdbc driver that will be used

Since:

1.0

See Also:

getDriver()

getDataSource

public DataSource getDataSource()

Retrieves the standard datasource that is used by this RIFE datasource to obtain a database connection.

Returns:

a standard DataSource; or

null if the standard datasource hasn't been set

Since:

1.3

See Also:

setDataSource(DataSource)

setDataSource

public void setDataSource(DataSource dataSource)

Sets the standard datasource that will be used to connect to the database.

Parameters:

dataSource - a standard DataSource that will be used by this RIFE datasource to obtain a database connection.

Since:

1.0

See Also:

getDataSource()

getUrl

public String getUrl()

Retrieves the connection url that's used by this Datasource.

Returns:

a String with the connection url; or

null if the url hasn't been set

Since:

1.0

See Also:

setUrl(String)

setUrl

public void setUrl(String url)

Sets the connection url that will be used to connect to the database. It's not possible to change the url after a connection has been obtained from a pooled datasource.

Parameters:

url - a String with the connection url that will be used

Since:

1.0

See Also:

getUrl()

getUser

public String getUser()

Retrieves the user that's used by this Datasource.

Returns:

a String>/code> with the user; or

null if the user hasn't been set

Since:

1.0

See Also:

setUser(String)

setUser

public void setUser(String user)

Sets the user that will be used to connect to the database. It's not possible to change the user after a connection has been obtained from a pooled datasource.

Parameters:

user - a String with the user that will be used

Since:

1.0

See Also:

getUser()

getPassword

public String getPassword()

Retrieves the password that's used by this Datasource.

Returns:

a String>/code> with the password; or

null if the password hasn't been set

Since:

1.0

See Also:

setPassword(String)

setPassword

public void setPassword(String password)

Sets the password that will be used to connect to the database. It's not possible to change the password after a connection has been obtained from a pooled datasource.

Parameters:

password - a String with the password that will be used

Since:

1.0

See Also:

getPassword()

getPoolsize

public int getPoolsize()

Retrieves the size of the pool that's used by this Datasource.

Returns:

a positive int with the size of the pool; or

0 if no pool is being used

Since:

1.0

See Also:

isPooled(), setPoolsize(int)

isPooled

public boolean isPooled()

Indicates whether the Datasource uses a connection pool or not

Returns:

true if a pool is being used by this Datasource; or

false otherwise

Since:

1.0

See Also:

getPoolsize(), setPoolsize(int)

setPoolsize

public void setPoolsize(int poolsize)

Sets the size of the connection pool that will be used to connect to the database.

Parameters:

poolsize - a positive int with the size of the pool, providing 0 will disable the use of a connection pool for this Datasource.

Since:

1.0

See Also:

getPoolsize(), isPooled()

getSqlConversion

public SqlConversion getSqlConversion()
                               throws UnsupportedJdbcDriverException

Retrieves the sql to java and java to sql type mapping logic that corresponds to the provide driver class name.

Returns:

a SqlConversion instance that is able to perform the required type conversions for the provided jdbc driver

Throws:

UnsupportedJdbcDriverException - when the provided jdbc isn't supported

Since:

1.0

getCapabilitiesCompensator

public com.uwyn.rife.database.capabilities.CapabilitiesCompensator getCapabilitiesCompensator()
                                                                                       throws UnsupportedJdbcDriverException

Retrieves a CapabilitiesCompensator instance that is able to compensate for certain missing database features

Returns:

the requested CapabilitiesCompensator instance

Throws:

UnsupportedJdbcDriverException - when the provided jdbc isn't supported

Since:

1.0

hashCode

public int hashCode()

Returns a hash code value for the Datasource. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

Overrides:

hashCode in class Object

Returns:

an int with the hash code value for this Datasource.

Since:

1.0

See Also:

equals(Object)

equals

public boolean equals(Object object)

Indicates whether some other object is "equal to" this one. Only the real connection parameters will be taken into account. The size of the pool is not used for the comparison.

Overrides:

equals in class Object

Parameters:

object - the reference object with which to compare.

Returns:

true if this object is the same as the object argument; or

false otherwise

Since:

1.0

See Also:

hashCode()

clone

public Datasource clone()

Simply clones the instance with the default clone method. This creates a shallow copy of all fields and the clone will in fact just be another reference to the same underlying data. The independence of each cloned instance is consciously not respected since they rely on resources that can't be cloned.

Overrides:

clone in class Object

Since:

1.0

cleanup

public void cleanup()
             throws DatabaseException

Cleans up all connections that have been reserved by this datasource.

Throws:

DatabaseException - when an error occured during the cleanup

Since:

1.0

getPool

public ConnectionPool getPool()

Retrieves the instance of the connection pool that is provided by this dtaasource.

Returns:

the requested instance of ConnectionPool