Package com.jk.data.dataaccess.core

Interface JKDataAccessService

All Known Implementing Classes:
H2DataAccess, JKDataAccessImpl, JKOracleDataAccess, MysqlDataAccess
public interface JKDataAccessService
This interface defines methods for interacting with a database, executing queries, and managing transactions.
Version:
1.0
Author:
Dr. Jalal H. Kiswani

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beginTransaction()
    This method begins a new database transaction.
    <T> T
    call(JKCaller caller)
    This method executes a database operation defined by the provided JKCaller.
    List
    call(String call, List<Object> params, List<Class<?>> outClasses)
    This method executes a database stored procedure or function and returns the result as a list.
    default <T> T
    callAsSingleOutput(String call, List<Object> params, List<Class<?>> outClasses)
    This method executes a database stored procedure or function and returns a single output value.
    void
    closeTransaction(boolean commit)
    This method closes the current database transaction, either committing or rolling it back based on the specified parameter.
    Map<String,String>
    describeTable(String name)
    This method retrieves data about a database table and returns it as a map of column names to their corresponding data types.
    void
    dropTable(String string)
    This method drops a database table specified by its name.
    int
    execute(String sql, Object... params)
    This method executes a database operation with the provided SQL statement and optional parameters.
    Object[]
    executeQueryAsArray(String query, Object... params)
    This method executes a SQL query and returns the result as an array of objects.
    CachedRowSet
    executeQueryAsCachedRowSet(String query, Object... params)
    This method executes a database query and returns the result as a CachedRowSet.
    default double
    executeQueryAsDouble(String query, Object... params)
    This method executes an SQL query and returns the result as a double value.
    List<JKDbIdValue>
    executeQueryAsIdValue(String sql, Object... params)
    This method executes a database query and returns the result as a list of JKDbIdValue objects.
    default int
    executeQueryAsInteger(String query, Object... params)
    This method executes an SQL query and returns the result as an integer value.
    List<List<Object>>
    executeQueryAsList(String query, Object... params)
    This method executes a query and returns the result as a List of rows, where each row is represented as a List of objects.
    default <T> List<T>
    executeQueryAsListOfObjects(Class<T> clas, String query, Object... params)
    This method executes an SQL query and returns the result as a list of objects of the specified class.
    default <T> List<T>
    executeQueryAsListOfObjects(Class<T> clas, Map<String,Object> fieldsMapping, String query, Object... params)
    This method executes an SQL query and returns the result as a list of objects of the specified class.
    default long
    executeQueryAsLong(String query, Object... params)
    This method executes an SQL query and returns the result as a long value.
    default <T> Map<Object,T>
    executeQueryAsMap(String sql, Object... params)
    This method executes a SQL query and returns the result as a map where keys are objects and values are of type T.
    default Object[]
    executeQueryAsRow(String query, Object... params)
    This method executes an SQL query and returns the result as an array representing a single row.
    String
    executeQueryAsString(String query, Object... params)
    This method executes an SQL query and returns the result as a formatted string.
    String
    executeQueryAsString(String query, String fieldSeparator, String recordsSepartor, Object... params)
    This method executes an SQL query and returns the result as a formatted string with custom separators.
    Object
    executeSingleOutputQuery(String query, Object... params)
    This method executes a database query that is expected to return a single value and retrieves that value.
    Object
    executeUpdate(JKUpdater updater)
    This method executes a database update operation using a JKUpdater and returns the result.
    Object
    executeUpdate(JKUpdater updater, boolean ignoreRecordNotFoundException)
    This method executes an update operation using the provided JKUpdater and allows for ignoring the JKRecordNotFoundException.
    Object
    executeUpdate(String sql, Object... objects)
    This method executes an SQL update statement with optional parameters and returns the result.
    <T> T
    find(String query, JKPopulator<T> populator, Object... params)
    This method executes an SQL query and maps the result to an object using a provided JKPopulator.
    <T> T
    findAndCacheRecord(String tableName, String query, JKPopulator<T> populator, Object... params)
    This method executes an SQL query, maps the result to an object using a provided populator, and caches the mapped object using the specified table name.
    <T> T
    findRecord(JKFinder finder)
    This method finds and retrieves a record from the database table based on the provided JKFinder criteria.
    <T> T
    findRecord(JKFinder finder, String tableName, Object recordId)
    This method finds and retrieves a specific record from the specified database table using the provided JKFinder and record ID.
    <T> List<T>
    getList(JKFinder finder)
    This method retrieves a list of objects based on the provided JKFinder criteria.
    <T> List<T>
    getList(JKFinder finder, String key)
    Gets the list.
    <T> List<T>
    getList(String query, JKPopulator<T> populator, Object... params)
    This method executes an SQL query and maps the result to a list of objects using a provided populator.
    <T> List<T>
    getListAndCache(String tableName, String query, JKPopulator<T> populator, Object... params)
    This method executes an SQL query, maps the result to a list of objects using a provided populator, and caches the result for future use.
    Long
    getNextId(String tableName, String fieldName)
    This method retrieves the next available ID for a specified table and field.
    Long
    getNextId(String tableName, String fieldName, String condition)
    This method retrieves the next available ID for a specified table and field based on a given condition.
    int
    getRowsCount(String query, Object... params)
    This method retrieves the number of rows returned by a specified SQL query with optional parameters.
    Date
    getSystemDate()
    This method retrieves the current system date and time from the database.
    default String
    getTenantId()
    This method gets the tenant identifier (ID).
    boolean
    isTableExists(String tableName)
    This method checks whether the table with the provided name exists in the database or not.
    void
    runScript(String fileName)
    This method runs a SQL script from a specified file.

  • Method Details

    • executeQueryAsCachedRowSet

      CachedRowSet executeQueryAsCachedRowSet(String query, Object... params)
      This method executes a database query and returns the result as a CachedRowSet.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to bind to the query.
      Returns:
      the CachedRowSet containing the query results.

    • executeQueryAsIdValue

      List<JKDbIdValue> executeQueryAsIdValue(String sql, Object... params)
      This method executes a database query and returns the result as a list of JKDbIdValue objects.
      Parameters:
      sql - Specifies the SQL query to execute.
      params - Specifies the optional parameters to bind to the query.
      Returns:
      a list of JKDbIdValue objects representing the query results

    • executeUpdate

      Object executeUpdate(JKUpdater updater)
      This method executes a database update operation using a JKUpdater and returns the result.
      Parameters:
      updater - Specifies the JKUpdater object that defines the update operation.
      Returns:
      the result of the update operation, which can be a generated key or another relevant value.

    • execute

      int execute(String sql, Object... params)
      This method executes a database operation with the provided SQL statement and optional parameters.
      Parameters:
      sql - Specifies the SQL statement to execute.
      params - Specifies the parameters to be bound to the SQL statement.
      Returns:
      the number of rows affected by the operation.

    • executeSingleOutputQuery

      Object executeSingleOutputQuery(String query, Object... params)
      This method executes a database query that is expected to return a single value and retrieves that value.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the parameters to be bound to the SQL query.
      Returns:
      the single value returned by the query, or null if no value is found.

    • getNextId

      Long getNextId(String tableName, String fieldName)
      This method retrieves the next available ID for a specified table and field.
      Parameters:
      tableName - Specifies the name of the database table.
      fieldName - Specifies the name of the field for which the next ID is needed.
      Returns:
      the next available ID for the specified table and field.

    • getNextId

      Long getNextId(String tableName, String fieldName, String condition)
      This method retrieves the next available ID for a specified table and field based on a given condition.
      Parameters:
      tableName - Specifies the name of the database table.
      fieldName - Specifies the name of the field for which the next ID is needed.
      condition - Specifies the condition that filters the records to determine the next ID.
      Returns:
      the next available ID for the specified table, field, and condition.

    • getRowsCount

      int getRowsCount(String query, Object... params)
      This method retrieves the number of rows returned by a specified SQL query with optional parameters.
      Parameters:
      query - Specifies the SQL query for which row count is to be determined.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the number of rows returned by the specified SQL query.

    • executeQueryAsString

      String executeQueryAsString(String query, Object... params)
      This method executes an SQL query and returns the result as a formatted string.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the formatted string representation of the query result.

    • executeQueryAsString

      String executeQueryAsString(String query, String fieldSeparator, String recordsSepartor, Object... params)
      This method executes an SQL query and returns the result as a formatted string with custom separators.
      Parameters:
      query - Specifies the SQL query to execute.
      fieldSeparator - Specifies the separator used to separate fields in the result.
      recordsSepartor - Specifies the separator used to separate records in the result.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the formatted string representation of the query result with custom separators.

    • executeUpdate

      Object executeUpdate(JKUpdater updater, boolean ignoreRecordNotFoundException)
      This method executes an update operation using the provided JKUpdater and allows for ignoring the JKRecordNotFoundException.
      Parameters:
      updater - Specifies the JKUpdater object responsible for specifying the update operation
      ignoreRecordNotFoundException - Indicates whether to ignore the JKRecordNotFoundException if no records are affected by the update
      Returns:
      the generated key if applicable, or null.

    • executeQueryAsList

      List<List<Object>> executeQueryAsList(String query, Object... params)
      This method executes a query and returns the result as a List of rows, where each row is represented as a List of objects.
      Parameters:
      query - Specifies the SQL query to be executed.
      params - Specifies the optional parameters to be used in the query.
      Returns:
      the list of rows, where each row is represented as a List of Objects.

    • findRecord

      <T> T findRecord(JKFinder finder, String tableName, Object recordId)
      This method finds and retrieves a specific record from the specified database table using the provided JKFinder and record ID.
      Type Parameters:
      T - Specifies the type of the record object.
      Parameters:
      finder - Specifies the JKFinder instance specifying the criteria for the record retrieval.
      tableName - Specifies the name of the database table from which to retrieve the record.
      recordId - Specifies the unique identifier of the record to be retrieved.
      Returns:
      the retrieved record as an object of type T, or null if the record is not found.

    • findRecord

      <T> T findRecord(JKFinder finder)
      This method finds and retrieves a record from the database table based on the provided JKFinder criteria.
      Type Parameters:
      T - Specifies the type of the record object.
      Parameters:
      finder - Specifies the JKFinder instance specifying the criteria for the record retrieval.
      Returns:
      the retrieved record as an object of type T, or null if the record is not found.

    • getSystemDate

      Date getSystemDate()
      This method retrieves the current system date and time from the database.
      Returns:
      a Date object representing the current system date and time

    • getList

      <T> List<T> getList(JKFinder finder)
      This method retrieves a list of objects based on the provided JKFinder criteria.
      Type Parameters:
      T - Specifies the type of the record object.
      Parameters:
      finder - Specifies the JKFinder instance specifying the criteria for the record retrieval.
      Returns:
      a list of objects that match the criteria defined in the JKFinder.

    • getList

      <T> List<T> getList(JKFinder finder, String key)
      Gets the list.
      Type Parameters:
      T - the generic type
      Parameters:
      finder - the finder
      key - the key
      Returns:
      the list

    • executeQueryAsArray

      Object[] executeQueryAsArray(String query, Object... params)
      This method executes a SQL query and returns the result as an array of objects.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the query.
      Returns:
      an array of objects representing the result of the query.

    • isTableExists

      boolean isTableExists(String tableName)
      This method checks whether the table with the provided name exists in the database or not.
      Parameters:
      tableName - Specifies the table name in the database.
      Returns:
      true, if the table exists, false otherwise.

    • runScript

      void runScript(String fileName)
      This method runs a SQL script from a specified file.
      Parameters:
      fileName - Specifies the name of the file containing the SQL script to execute.

    • dropTable

      void dropTable(String string)
      This method drops a database table specified by its name.
      Parameters:
      string - Specifies the name of the table to drop.

    • executeUpdate

      Object executeUpdate(String sql, Object... objects)
      This method executes an SQL update statement with optional parameters and returns the result.
      Parameters:
      sql - Specifies the SQL update statement to execute.
      objects - Specifies an optional array of parameters to be used in the SQL statement.
      Returns:
      the object representing the result of the update operation.

    • executeQueryAsLong

      default long executeQueryAsLong(String query, Object... params)
      This method executes an SQL query and returns the result as a long value.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the result of the query as a long value.

    • executeQueryAsDouble

      default double executeQueryAsDouble(String query, Object... params)
      This method executes an SQL query and returns the result as a double value.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the result of the query as a double value.

    • executeQueryAsRow

      default Object[] executeQueryAsRow(String query, Object... params)
      This method executes an SQL query and returns the result as an array representing a single row.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      an array representing a single row of the query result, or null if no rows were found.

    • executeQueryAsListOfObjects

      default <T> List<T> executeQueryAsListOfObjects(Class<T> clas, String query, Object... params)
      This method executes an SQL query and returns the result as a list of objects of the specified class.
      Type Parameters:
      T - Specifies the type of objects to be created and returned.
      Parameters:
      clas - Specifies the class representing the type of objects to be created from the query result.
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      a list of objects of the specified class representing the query result.

    • executeQueryAsListOfObjects

      default <T> List<T> executeQueryAsListOfObjects(Class<T> clas, Map<String,Object> fieldsMapping, String query, Object... params)
      This method executes an SQL query and returns the result as a list of objects of the specified class.
      Type Parameters:
      T - Specifies the type of objects to be created and returned.
      Parameters:
      clas - Specifies the class representing the type of objects to be created from the query result.
      fieldsMapping - Specifies a map that defines the mapping between field names in the query result and properties in the target class.
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the list of objects of the specified class representing the query result.

    • executeQueryAsInteger

      default int executeQueryAsInteger(String query, Object... params)
      This method executes an SQL query and returns the result as an integer value.
      Parameters:
      query - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the integer representing the query result.

    • find

      <T> T find(String query, JKPopulator<T> populator, Object... params)
      This method executes an SQL query and maps the result to an object using a provided JKPopulator.
      Type Parameters:
      T - Specifies the type of objects.
      Parameters:
      query - Specifies the SQL query to execute.
      populator - Specifies the JKPopulator instance responsible for mapping the query result to an object
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      an object resulting from the query execution and mapping.

    • findAndCacheRecord

      <T> T findAndCacheRecord(String tableName, String query, JKPopulator<T> populator, Object... params)
      This method executes an SQL query, maps the result to an object using a provided populator, and caches the mapped object using the specified table name.
      Type Parameters:
      T - Specifies the type of objects.
      Parameters:
      tableName - Specifies the name of the table associated with the cached record.
      query - Specifies the SQL query to execute.
      populator - Specifies the JKPopulator instance responsible for mapping the query result to an object.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      an object resulting from the query execution and mapping, cached under the specified table name.

    • getList

      <T> List<T> getList(String query, JKPopulator<T> populator, Object... params)
      This method executes an SQL query and maps the result to a list of objects using a provided populator.
      Type Parameters:
      T - Specifies the type of objects.
      Parameters:
      query - Specifies the SQL query to execute.
      populator - Specifies the JKPopulator instance responsible for mapping the query result to an object.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the list of objects resulting from the query execution and mapping.

    • getListAndCache

      <T> List<T> getListAndCache(String tableName, String query, JKPopulator<T> populator, Object... params)
      This method executes an SQL query, maps the result to a list of objects using a provided populator, and caches the result for future use.
      Type Parameters:
      T - Specifies the type of objects.
      Parameters:
      tableName - Specifies the name of the table associated with the query.
      query - Specifies the SQL query to execute.
      populator - Specifies the JKPopulator instance responsible for mapping the query result to an object.
      params - Specifies the optional parameters to be used in the SQL query.
      Returns:
      the list of objects resulting from the query execution and mapping.

    • describeTable

      Map<String,String> describeTable(String name)
      This method retrieves data about a database table and returns it as a map of column names to their corresponding data types.
      Parameters:
      name - Specifies the name of the table to describe.
      Returns:
      the map containing column names as keys and their corresponding data types as values.

    • beginTransaction

      void beginTransaction()
      This method begins a new database transaction.

    • closeTransaction

      void closeTransaction(boolean commit)
      This method closes the current database transaction, either committing or rolling it back based on the specified parameter.
      Parameters:
      commit - Indicates whether the transaction will be committed (true), or if it will be rolled back (false).

    • executeQueryAsMap

      default <T> Map<Object,T> executeQueryAsMap(String sql, Object... params)
      This method executes a SQL query and returns the result as a map where keys are objects and values are of type T.
      Type Parameters:
      T - Specifies the type of objects.
      Parameters:
      sql - Specifies the SQL query to execute.
      params - Specifies the optional parameters to be used in the SQL query
      Returns:
      the map containing the query results with keys as objects and values of type T.

    • getTenantId

      default String getTenantId()
      This method gets the tenant identifier (ID).
      Returns:
      the tenant identifier (ID).

    • call

      List call(String call, List<Object> params, List<Class<?>> outClasses)
      This method executes a database stored procedure or function and returns the result as a list.
      Parameters:
      call - Specifies the name of the stored procedure or function to call.
      params - Specifies the parameters to pass to the stored procedure or function.
      outClasses - Specifies the classes of the output parameters.
      Returns:
      the list containing the result of the stored procedure or function execution.

    • callAsSingleOutput

      default <T> T callAsSingleOutput(String call, List<Object> params, List<Class<?>> outClasses)
      This method executes a database stored procedure or function and returns a single output value.
      Type Parameters:
      T - Specifies the type of the output value.
      Parameters:
      call - Specifies the name of the stored procedure or function to call.
      params - Specifies the parameters to pass to the stored procedure or function.
      outClasses - Specifies the classes of the output parameters.
      Returns:
      the single output value of the stored procedure or function execution.

    • call

      <T> T call(JKCaller caller)
      This method executes a database operation defined by the provided JKCaller.
      Type Parameters:
      T - Specifies the type of the result returned by the database operation.
      Parameters:
      caller - Specifies the JKCaller that defines the database operation.
      Returns:
      the result of the database operation.