Package ortus.boxlang.runtime.jdbc

Class DataSource

java.lang.Object
ortus.boxlang.runtime.jdbc.DataSource
All Implemented Interfaces:
Comparable<DataSource>
public class DataSource extends Object implements Comparable<DataSource>
Encapsulates a datasource configuration and connection pool, providing methods for executing queries (transactionally or single) on the datasource.

  • Constructor Details

    • DataSource

      public DataSource(DatasourceConfig config)
      Configure and initialize a new DataSourceRecord object from a struct of properties.
      Parameters:
      config - A struct of properties to configure the datasource. Hikari itself will require either `dataSourceClassName` or `jdbcUrl` to be defined, and potentially `username` and `password` as well.

  • Method Details

    • fromStruct

      public static DataSource fromStruct(String name, IStruct properties)
      Helper builder to build out a new DataSource object from a struct of properties and a name.
      Parameters:
      name - The string name of the datasource.
      properties - A struct of properties to configure the datasource. Will likely be defined via Application.bx or a web admin.
      Returns:
      a DataSource object configured from the provided struct.

    • fromStruct

      public static DataSource fromStruct(Key name, IStruct properties)
      Helper builder to build out a new DataSource object from a struct of properties and a name.
      Parameters:
      name - The name of the datasource.
      properties - A struct of properties to configure the datasource. Will likely be defined via Application.bx or a web admin.
      Returns:
      a DataSource object configured from the provided struct.

    • getOriginalName

      public String getOriginalName()
      Get the original name of the datasource - this is NOT unique and should not be used for identification.
      Returns:
      The original name of the datasource.

    • getUniqueName

      public Key getUniqueName()
      Get a unique datasource name which includes a hash of the properties Following the pattern: bx_{name}_{properties_hash}

    • isOnTheFly

      public Boolean isOnTheFly()
      Are we an on the fly datasource?

    • hashCode

      public int hashCode()
      Get's the hashcode according to the datasource's unique name
      Overrides:
      hashCode in class Object
      Returns:
      the hashcode

    • equals

      public boolean equals(Object obj)
      Verifies equality between two Datasource objects
      Overrides:
      equals in class Object
      Parameters:
      obj - The other object to compare

    • compareTo

      public int compareTo(DataSource otherConfig)
      Compares two DataSource objects
      Specified by:
      compareTo in interface Comparable<DataSource>
      Parameters:
      otherConfig - The other DataSource object to compare
      Returns:
      A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • getConfiguration

      public DatasourceConfig getConfiguration()
      Get the configuration object for this datasource.
      Returns:
      The configuration object for this datasource.

    • getConnection

      public Connection getConnection()
      Get a connection to the configured datasource.
      Returns:
      A JDBC connection to the configured datasource.
      Throws:
      BoxRuntimeException - if connection could not be established.

    • getUnpooledConnection

      protected Connection getUnpooledConnection()

    • getConnection

      public Connection getConnection(String username, String password)
      Get a connection to the configured datasource with the provided username and password.
      Returns:
      A JDBC connection to the configured datasource.
      Throws:
      BoxRuntimeException - if connection could not be established.

    • shutdown

      public DataSource shutdown()
      Shut down the datasource, including the connection pool and all connections.
      Returns:
      This DataSource object, which is now shut down and useless for any further operations.

    • execute

      public ExecutedQuery execute(String query)
      Execute a query on the default connection.
      Parameters:
      query - The SQL query to execute.
      Returns:
      An array of Structs, each representing a row of the result set (if any). If there are no results (say, for an UPDATE statement), an empty array is returned.

    • execute

      public ExecutedQuery execute(String query, IBoxContext context)
      Execute a query on the default connection, within the specific context.
      Parameters:
      query - The SQL query to execute.
      context - The boxlang context for localization. Useful for localization; i.e., queries with date or time values.

    • execute

      public ExecutedQuery execute(String query, Connection conn, IBoxContext context)
      Execute a query on the connection, using the provided connection.

      Note the connection passed in is NOT closed automatically. It is up to the caller to close the connection when they are done with it. If you want an automanaged, i.e. autoclosed connection, use the execute(String) method.

      Parameters:
      query - The SQL query to execute.
      conn - The connection to execute the query on. A connection is required - use execute(String) if you don't wish to provide one.
      Returns:
      An array of Structs, each representing a row of the result set (if any). If there are no results (say, for an UPDATE statement), an empty array is returned.

    • execute

      public ExecutedQuery execute(String query, List<QueryParameter> parameters, Connection conn, IBoxContext context)
      Execute a query with a List of parameters on a given connection.

    • execute

      public ExecutedQuery execute(String query, List<QueryParameter> parameters, IBoxContext context)
      Execute a query with a List of parameters on the default connection.

    • execute

      public ExecutedQuery execute(String query, Array parameters, Connection conn, IBoxContext context)
      Execute a query with an array of parameters on a given connection.

    • execute

      public ExecutedQuery execute(String query, Array parameters, IBoxContext context)
      Execute a query with an array of parameters on the default connection.

    • execute

      public ExecutedQuery execute(String query, IStruct parameters, Connection conn, IBoxContext context)
      Execute a query with a struct of parameters on a given connection.

    • execute

      public ExecutedQuery execute(String query, IStruct parameters, IBoxContext context)
      Execute a query with a struct of parameters on the default connection.

    • isAuthenticationMatch

      public Boolean isAuthenticationMatch(String username, String password)
      Check the provided username and password against the current datasource credentials.

      For obvious reasons, the string comparison is case-sensitive.

      Parameters:
      username - Username to check against the established datasource
      password - Password to check against the established datasource
      Returns:
      True if the username and password match.

    • getHikariDataSource

      public com.zaxxer.hikari.HikariDataSource getHikariDataSource()
      Allow access to the underlying HikariDataSource object.
      Returns:
      The HikariDataSource object.

    • getPoolStats

      public IStruct getPoolStats()
      Get the current pool statistics for the datasource.
      Returns:
      A struct containing the current pool statistics, including active connections, idle connections, and total connections.