Package tigase.db

## Interface DataRepository

- All Superinterfaces:
    `DataSource`, `Repository`
  All Known Implementing Classes:
    `DataRepositoryImpl`, `DataRepositoryPool`

      public interface DataRepository
      extends DataSource

  The interface defines a generic data repository for storing arbitrary data in any application specific form. This interface unifies database (repository) access allowing for easier way to create database connections pools or database fail-over mechanisms.
  Created: Jun 16, 2010 3:34:32 PM
  Author:
    Artur Hefczyc

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `DataRepository.dbTypes` | Helper enumeration with types of supported databases.

    - ### Nested classes/interfaces inherited from interface tigase.db.Repository

      `Repository.Meta, Repository.SchemaId`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.util.Calendar` | `UTC_CALENDAR` |

    - ### Fields inherited from interface tigase.db.DataSource

      `log`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `checkTable​(java.lang.String tableName)` | The method checks whether a table for the given name exists in the database.
    `boolean` | `checkTable​(java.lang.String tableName, java.lang.String createTableQuery)` | The method checks whether a table for the given name exists in the database and if it does not, it automatically creates it.
    `void` | `commit()` | Commits current transaction on the DataRepository connection.
    `java.sql.Statement` | `createStatement​(BareJID user_id)` | Creates a SQL statement on which SQL queries can be executed later by the higher repository layer.
    `void` | `endTransaction()` | Ends current transaction on the DataRepository connection.
    `DataRepository.dbTypes` | `getDatabaseType()` | Returns type of DataRepository database
    `int` | `getPoolSize()` |
    `java.sql.PreparedStatement` | `getPreparedStatement​(int hashCode, java.lang.String stIdKey)` | Returns a prepared statement for a given key.
    `java.sql.PreparedStatement` | `getPreparedStatement​(BareJID user_id, java.lang.String stIdKey)` | Returns a prepared statement for a given key.
    `java.lang.String` | `getResourceUri()` | Returns a DB connection string or DB connection URI.
    `default java.sql.Timestamp` | `getTimestamp​(java.sql.ResultSet rs, int pos)` | Helper method to get timestamp from result set.
    `default java.sql.Timestamp` | `getTimestamp​(java.sql.ResultSet rs, java.lang.String field)` | Helper method to get timestamp from result set.
    `void` | `initPreparedStatement​(java.lang.String stIdKey, java.lang.String query)` | Initializes a prepared statement for a given query and stores it internally under the given id key.
    `void` | `initPreparedStatement​(java.lang.String stIdKey, java.lang.String query, int autoGeneratedKeys)` | Initializes a prepared statement for a given query and stores it internally under the given id key.
    `void` | `release​(java.sql.Statement stmt, java.sql.ResultSet rs)` | A helper method to release resources from the statement and result set.
    `void` | `releaseRepoHandle​(DataRepository repo)` |
    `void` | `rollback()` | Rolls back started transaction on the DataRepository connection.
    `default void` | `setTimestamp​(java.sql.PreparedStatement stmt, int pos, java.sql.Timestamp timestamp)` | Helper method to set timestamp into prepared statements.
    `void` | `startTransaction()` | Starts transaction on the DataRepository connection.
    `DataRepository` | `takeRepoHandle​(BareJID user_id)` | Returns `DataRepository` instance.

    - ### Methods inherited from interface tigase.db.DataSource

      `automaticSchemaManagement, checkConnectivity, checkSchemaVersion, getSchemaVersion, initialize`

    - ### Methods inherited from interface tigase.db.Repository

      `initRepository`

- - ### Field Detail

    - #### UTC_CALENDAR

          static final java.util.Calendar UTC_CALENDAR

  - ### Method Detail

    - #### checkTable

          boolean checkTable​(java.lang.String tableName)
                      throws java.sql.SQLException

      The method checks whether a table for the given name exists in the database.
      Parameters:
        `tableName` - is a `String` value of the table name to check
      Returns:
        `true` `boolean` value if the table exist in the database and `false` if the table was not found.
      Throws:
        `java.sql.SQLException` - if there was a problem accessing database.

    - #### checkTable

          boolean checkTable​(java.lang.String tableName,
                             java.lang.String createTableQuery)
                      throws java.sql.SQLException

      The method checks whether a table for the given name exists in the database and if it does not, it automatically creates it.
      Parameters:
        `tableName` - is a `String` value of the table name to check
        `createTableQuery` - is a `String` with the query to create table
      Returns:
        `true` `boolean` value if the table exist in the database and `false` if the table was not found.
      Throws:
        `java.sql.SQLException` - if there was a problem accessing database.

    - #### commit

          void commit()
               throws java.sql.SQLException

      Commits current transaction on the DataRepository connection. Please note that calling this method on the repository pool has no effect. You have to obtain particular repository handle first, before you can start transaction.
      Throws:
        `java.sql.SQLException`

    - #### createStatement

          java.sql.Statement createStatement​(BareJID user_id)
                                      throws java.sql.SQLException

      Creates a SQL statement on which SQL queries can be executed later by the higher repository layer.
      Parameters:
        `user_id` - user id for which the statement has to be created. This is an optional parameter and null can be provided. It is used mainly to group queries for the same user on the same DB connection.
      Returns:
        a newly created `Statement`
      Throws:
        `java.sql.SQLException` - if a JDBC error occurs.

    - #### endTransaction

          void endTransaction()
                       throws java.sql.SQLException

      Ends current transaction on the DataRepository connection. Please note that calling this method on the repository pool has no effect. You have to obtain particular repository handle first, before you can start transaction.
      Throws:
        `java.sql.SQLException`

    - #### initPreparedStatement

          void initPreparedStatement​(java.lang.String stIdKey,
                                     java.lang.String query)
                              throws java.sql.SQLException

      Initializes a prepared statement for a given query and stores it internally under the given id key. It can be retrieved later using `getPreparedStatement(stIdKey)` method.
      Parameters:
        `stIdKey` - is a statement identification key.
        `query` - is a query for the prepared statement.
      Throws:
        `java.sql.SQLException`

    - #### initPreparedStatement

          void initPreparedStatement​(java.lang.String stIdKey,
                                     java.lang.String query,
                                     int autoGeneratedKeys)
                              throws java.sql.SQLException

      Initializes a prepared statement for a given query and stores it internally under the given id key. It can be retrieved later using `getPreparedStatement(stIdKey)` method.
      Parameters:
        `stIdKey` - is a statement identification key.
        `query` - is a query for the prepared statement.
        `autoGeneratedKeys` - defines if statement should return auto generated keys
      Throws:
        `java.sql.SQLException`

    - #### release

          void release​(java.sql.Statement stmt,
                       java.sql.ResultSet rs)

      A helper method to release resources from the statement and result set. This is most common operation for all database calls, therefore it does make sense to add such a utility method to the API.
      Parameters:
        `stmt` - a `Statement` variable to release resources for. Might be null.
        `rs` - a `ResultSet` variable to release resources for. Might be null.

    - #### releaseRepoHandle

          void releaseRepoHandle​(DataRepository repo)

    - #### rollback

          void rollback()
                 throws java.sql.SQLException

      Rolls back started transaction on the DataRepository connection. Please note that calling this method on the repository pool has no effect. You have to obtain particular repository handle first, before you can start transaction.
      Throws:
        `java.sql.SQLException`

    - #### startTransaction

          void startTransaction()
                         throws java.sql.SQLException

      Starts transaction on the DataRepository connection. Please note that calling this method on the repository pool has no effect. You have to obtain particular repository handle first, before you can start transaction.
      Throws:
        `java.sql.SQLException`

    - #### takeRepoHandle

          DataRepository takeRepoHandle​(BareJID user_id)

      Returns `DataRepository` instance. If this is a repository pool then it returns particular instance from the pool. It this is a real repository instance it returns itself. This is exclusive take, no other thread may use this handle until it is returned to the pool.
      Parameters:
        `user_id` - is user account ID for which we acquire the handle.
      Returns:
        DataRepository instance.

    - #### getDatabaseType

          DataRepository.dbTypes getDatabaseType()

      Returns type of DataRepository database
      Returns:
        a value of `dbTypes`

    - #### getPoolSize

          int getPoolSize()

    - #### getPreparedStatement

          java.sql.PreparedStatement getPreparedStatement​(BareJID user_id,
                                                          java.lang.String stIdKey)
                                                   throws java.sql.SQLException

      Returns a prepared statement for a given key.
      Parameters:
        `user_id` - user id for which the statement has to be created. This is an optional parameter and null can be provided. It is used mainly to group queries for the same user on the same DB connection.
        `stIdKey` - is a statement identification key.
      Returns:
        a `PreparedStatement` for the given id key or null if such a statement does not exist.
      Throws:
        `java.sql.SQLException`

    - #### getPreparedStatement

          java.sql.PreparedStatement getPreparedStatement​(int hashCode,
                                                          java.lang.String stIdKey)
                                                   throws java.sql.SQLException

      Returns a prepared statement for a given key.
      Parameters:
        `hashCode` - user for selection of connection to use. It is used mainly to group queries for the same user on the same DB connection.
        `stIdKey` - is a statement identification key.
      Returns:
        a `PreparedStatement` for the given id key or null if such a statement does not exist.
      Throws:
        `java.sql.SQLException`

    - #### getResourceUri

          java.lang.String getResourceUri()

      Returns a DB connection string or DB connection URI.
      Specified by:
        `getResourceUri` in interface `DataSource`
      Returns:
        a `String` value representing database connection string.

    - #### setTimestamp

          default void setTimestamp​(java.sql.PreparedStatement stmt,
                                    int pos,
                                    java.sql.Timestamp timestamp)
                             throws java.sql.SQLException

      Helper method to set timestamp into prepared statements. Provides proper calendar when needed to adjust timestamps so that they are stored in the database in proper time zone.
      Throws:
        `java.sql.SQLException`

    - #### getTimestamp

          default java.sql.Timestamp getTimestamp​(java.sql.ResultSet rs,
                                                  int pos)
                                           throws java.sql.SQLException

      Helper method to get timestamp from result set. Provides proper calendar when needed to adjust timestamps so that they are stored in the database in proper time zone.
      Throws:
        `java.sql.SQLException`

    - #### getTimestamp

          default java.sql.Timestamp getTimestamp​(java.sql.ResultSet rs,
                                                  java.lang.String field)
                                           throws java.sql.SQLException

      Helper method to get timestamp from result set. Provides proper calendar when needed to adjust timestamps so that they are stored in the database in proper time zone.
      Throws:
        `java.sql.SQLException`