Package rife.database

Class Datasource

java.lang.Object
rife.database.Datasource
All Implemented Interfaces:
AutoCloseable, Cloneable
public class Datasource extends Object implements AutoCloseable, 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.

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
See Also:

  • Field Details

    • sDriverAliases

      public static HashMap<String,String> sDriverAliases

    • sDriverNames

      public static HashMap<String,String> sDriverNames

    • DRIVER_NAME_DERBY

      public static String DRIVER_NAME_DERBY

    • DRIVER_NAME_H2

      public static String DRIVER_NAME_H2

    • DRIVER_NAME_HSQLDB

      public static String DRIVER_NAME_HSQLDB

    • DRIVER_NAME_PGSQL

      public static String DRIVER_NAME_PGSQL

    • DRIVER_NAME_MYSQL

      public static String DRIVER_NAME_MYSQL

    • DRIVER_NAME_ORACLE

      public static String DRIVER_NAME_ORACLE

  • Constructor Details

    • Datasource

      public Datasource()
      Instantiates a new Datasource object with no connection information. The setters need to be used afterward to provide each required parameter before the Datasource can be used.
      Since:
      1.0
      See Also:

    • 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.0

    • 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.0

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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.0
      See Also:

    • 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:

    • 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

      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:

    • getUser

      public String getUser()
      Retrieves the user that's used by this Datasource.
      Returns:
      a String with the user; or null if the user hasn't been set
      Since:
      1.0
      See Also:

    • 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:

    • getPassword

      public String getPassword()
      Retrieves the password that's used by this Datasource.
      Returns:
      a String with the password; or null if the password hasn't been set
      Since:
      1.0
      See Also:

    • 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:

    • 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

      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:

    • 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:

    • 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 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

      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:

    • 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 occurred during the cleanup
      Since:
      1.0

    • close

      public void close() throws DatabaseException
      Specified by:
      close in interface AutoCloseable
      Throws:
      DatabaseException

    • getPool

      public ConnectionPool getPool()
      Retrieves the instance of the connection pool that is provided by this datasource.
      Returns:
      the requested instance of ConnectionPool

    • closeAllActiveDatasources

      public static void closeAllActiveDatasources()
      Closes all the active datasource.

      This can be used to ensure that no connections or drivers are dangling when an application shuts down. It's already used by the destroy method of the RifeFilter.

      Since:
      1.6.1