Package org.eclipse.net4j.db

## Class DBUtil

- java.lang.Object
- - org.eclipse.net4j.db.DBUtil

-     public final class DBUtil
      extends java.lang.Object

  A utility class with various static factory and convenience methods.
  Author:
    Eike Stepper

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `DBUtil.DeserializeRowHandler` | A `row handler` with a `method` that is called once per row deserialized within `DBUtil.deserializeTable()`.
    `static interface` | `DBUtil.RowHandler` | Call-back interface with a `method` that is called after a number of table rows have been handled by one of the subtypes of this interface.
    `static interface` | `DBUtil.RunnableWithConnection<T>` |
    `static interface` | `DBUtil.SerializeRowHandler` | A `row handler` with a `method` that is called once per row serialized within `DBUtil.serializeTable()`.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `MAX_BATCH_SIZE` |
    `static java.lang.String` | `PROP_ENABLE_NOISY_CLOSE` | A system property to enable noisy close, i.e.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static int` | `asInt​(java.lang.Object value)` |
    `static long` | `asLong​(java.lang.Object value)` |
    `static BatchedStatement` | `batched​(java.sql.PreparedStatement delegate, int batchSize)` |
    `static int` | `clearTable​(java.sql.Connection connection, java.lang.String tableName)` |
    `static int` | `clearTable​(java.sql.Connection connection, IDBTable table)` |
    `static java.lang.Exception` | `close​(java.sql.Connection connection)` |
    `static java.lang.Exception` | `close​(java.sql.ResultSet resultSet)` |
    `static java.lang.Exception` | `close​(java.sql.Statement statement)` |
    `static IDBSchema` | `copySchema​(IDBSchema source)` |
    `static IDBConnectionProvider` | `createConnectionProvider​(javax.sql.DataSource dataSource)` |
    `static IDBConnectionProvider2` | `createConnectionProvider​(javax.sql.DataSource dataSource, java.lang.String user)` |
    `static javax.sql.DataSource` | `createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties)` |
    `static javax.sql.DataSource` | `createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties, java.lang.String namespace)` |
    `static javax.sql.DataSource` | `createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties, java.lang.String namespace, java.lang.String driverClassKey)` |
    `static IDBSchema` | `createSchema​(java.lang.String name)` |
    `static void` | `deserializeTable​(org.eclipse.net4j.util.io.ExtendedDataInput in, java.sql.Connection connection, IDBTable table, org.eclipse.net4j.util.om.monitor.OMMonitor monitor)` |
    `static void` | `deserializeTable​(org.eclipse.net4j.util.io.ExtendedDataInput in, java.sql.Connection connection, IDBTable table, org.eclipse.net4j.util.om.monitor.OMMonitor monitor, DBUtil.DeserializeRowHandler handler)` |
    `static java.util.List<java.lang.Exception>` | `dropAllTables​(java.sql.Connection connection, java.lang.String dbName)` |
    `static void` | `dump​(IDBNamedElement namedElement)` |
    `static void` | `dump​(IDBNamedElement namedElement, java.io.Writer writer)` |
    `static java.lang.String` | `dumpToString​(IDBNamedElement namedElement)` |
    `static void` | `execute​(java.sql.Connection connection, java.lang.CharSequence sql)` |
    `static <T> T` | `execute​(IDBConnectionProvider connectionProvider, DBUtil.RunnableWithConnection<T> runnable)` |
    `static void` | `executeBatch​(java.sql.PreparedStatement stmt, int counter)` |
    `static void` | `executeBatch​(java.sql.PreparedStatement stmt, int counter, boolean checkExactlyOne)` |
    `static java.util.List<java.lang.String>` | `getAllSchemaNames​(java.sql.Connection connection)` |
    `static java.util.Set<java.lang.String>` | `getAllSchemaNames​(java.sql.DatabaseMetaData metaData)` |
    `static java.util.List<java.lang.String>` | `getAllSchemaTableNames​(java.sql.Connection connection)` | Deprecated. As of 4.2 use `getAllSchemaNames(Connection)`.
    `static java.util.List<java.lang.String>` | `getAllSchemaTableNames​(java.sql.DatabaseMetaData metaData)` | Deprecated. As of 4.2 use `getAllSchemaNames(DatabaseMetaData)`.
    `static java.util.List<java.lang.String>` | `getAllTableNames​(java.sql.Connection connection, java.lang.String dbName)` |
    `static IDBAdapter` | `getDBAdapter​(java.lang.String adapterName)` | Retrieves an `adapter` from the `adapter registry`.
    `static int` | `getRowCount​(java.sql.Connection connection, java.lang.String tableName)` | Returns the number of rows contained in the given table.
    `static int` | `getRowCount​(java.sql.ResultSet resultSet)` | Returns the number of rows contained in the given result set.
    `static boolean` | `isOptional​(IDBElement element)` |
    `static boolean` | `isTracerEnabled()` |
    `static IDBDatabase` | `openDatabase​(IDBAdapter adapter, IDBConnectionProvider connectionProvider, java.lang.String schemaName)` |
    `static IDBDatabase` | `openDatabase​(IDBAdapter adapter, IDBConnectionProvider connectionProvider, java.lang.String schemaName, boolean fixNullableIndexColumns)` |
    `static IDBSchema` | `readSchema​(IDBAdapter adapter, java.sql.Connection connection, java.lang.String name)` |
    `static IDBSchema` | `readSchema​(IDBAdapter adapter, java.sql.Connection connection, java.lang.String name, boolean fixNullableIndexColumns)` |
    `static void` | `readSchema​(IDBAdapter adapter, java.sql.Connection connection, IDBSchema schema)` |
    `static java.lang.Exception` | `rollbackSilently​(java.sql.Connection connection)` |
    `static java.lang.Object[]` | `select​(java.sql.Connection connection, java.lang.String where, IDBField... fields)` |
    `static int` | `select​(java.sql.Connection connection, IDBRowHandler rowHandler, java.lang.String where, IDBField... fields)` |
    `static int` | `select​(java.sql.Connection connection, IDBRowHandler rowHandler, IDBField... fields)` |
    `static int` | `selectMaximumInt​(java.sql.Connection connection, IDBField field, java.lang.String... where)` |
    `static long` | `selectMaximumLong​(java.sql.Connection connection, IDBField field, java.lang.String... where)` |
    `static int` | `selectMinimumInt​(java.sql.Connection connection, IDBField field, java.lang.String... where)` |
    `static long` | `selectMinimumLong​(java.sql.Connection connection, IDBField field, java.lang.String... where)` |
    `static void` | `serializeTable​(org.eclipse.net4j.util.io.ExtendedDataOutput out, java.sql.Connection connection, IDBTable table, java.lang.String tableAlias, java.lang.String sqlSuffix)` |
    `static void` | `serializeTable​(org.eclipse.net4j.util.io.ExtendedDataOutput out, java.sql.Connection connection, IDBTable table, java.lang.String tableAlias, java.lang.String sqlSuffix, DBUtil.SerializeRowHandler handler)` |
    `static boolean` | `setAutoCommit​(java.sql.Connection connection, boolean autoCommit)` |
    `static boolean` | `setOptional​(IDBElement element, boolean optional)` |
    `static void` | `sqlDump​(java.sql.Connection conn, java.lang.String sql)` | Deprecated. Should only be used when debugging.
    `static void` | `sqlDump​(IDBConnectionProvider connectionProvider, java.lang.String sql)` | Deprecated. Should only be used when debugging.
    `static java.lang.String` | `trace​(java.lang.String sql)` |
    `static int` | `update​(java.sql.Connection connection, java.lang.String sql)` |
    `static int` | `update​(java.sql.PreparedStatement stmt, boolean exactlyOne)` | Execute update on the given prepared statement and handle common cases of return values.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### MAX_BATCH_SIZE

          public static final int MAX_BATCH_SIZE

      Since:
        4.2

    - #### PROP_ENABLE_NOISY_CLOSE

          public static final java.lang.String PROP_ENABLE_NOISY_CLOSE

      A system property to enable noisy close, i.e. exception catch in close methods are thrown as `DBException` exception.
      Since:
        4.4
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### sqlDump

          @Deprecated
          public static void sqlDump​(java.sql.Connection conn,
                                     java.lang.String sql)

      Deprecated.
      Should only be used when debugging.
      For debugging purposes ONLY!
      Since:
        3.0

    - #### sqlDump

          @Deprecated
          public static void sqlDump​(IDBConnectionProvider connectionProvider,
                                     java.lang.String sql)

      Deprecated.
      Should only be used when debugging.
      For debugging purposes ONLY!
      Since:
        3.0

    - #### dumpToString

          public static java.lang.String dumpToString​(IDBNamedElement namedElement)

      Since:
        4.2

    - #### dump

          public static void dump​(IDBNamedElement namedElement)

      Since:
        4.2

    - #### dump

          public static void dump​(IDBNamedElement namedElement,
                                  java.io.Writer writer)
                           throws java.io.IOException

      Throws:
        `java.io.IOException`
      Since:
        4.2

    - #### openDatabase

          public static IDBDatabase openDatabase​(IDBAdapter adapter,
                                                 IDBConnectionProvider connectionProvider,
                                                 java.lang.String schemaName)

      Since:
        4.2

    - #### openDatabase

          public static IDBDatabase openDatabase​(IDBAdapter adapter,
                                                 IDBConnectionProvider connectionProvider,
                                                 java.lang.String schemaName,
                                                 boolean fixNullableIndexColumns)

      Since:
        4.2

    - #### createSchema

          public static IDBSchema createSchema​(java.lang.String name)

    - #### readSchema

          public static void readSchema​(IDBAdapter adapter,
                                        java.sql.Connection connection,
                                        IDBSchema schema)

      Since:
        4.2

    - #### readSchema

          public static IDBSchema readSchema​(IDBAdapter adapter,
                                             java.sql.Connection connection,
                                             java.lang.String name)

      Since:
        4.2

    - #### readSchema

          public static IDBSchema readSchema​(IDBAdapter adapter,
                                             java.sql.Connection connection,
                                             java.lang.String name,
                                             boolean fixNullableIndexColumns)

      Since:
        4.2

    - #### copySchema

          public static IDBSchema copySchema​(IDBSchema source)

      Since:
        4.2

    - #### createDataSource

          public static javax.sql.DataSource createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties)

    - #### createDataSource

          public static javax.sql.DataSource createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties,
                                                              java.lang.String namespace)

    - #### createDataSource

          public static javax.sql.DataSource createDataSource​(java.util.Map<java.lang.Object,​java.lang.Object> properties,
                                                              java.lang.String namespace,
                                                              java.lang.String driverClassKey)

    - #### createConnectionProvider

          public static IDBConnectionProvider createConnectionProvider​(javax.sql.DataSource dataSource)

    - #### createConnectionProvider

          public static IDBConnectionProvider2 createConnectionProvider​(javax.sql.DataSource dataSource,
                                                                        java.lang.String user)

      Since:
        4.3

    - #### getDBAdapter

          public static IDBAdapter getDBAdapter​(java.lang.String adapterName)

      Retrieves an `adapter` from the `adapter registry`.

      If Eclipse is running adapters are automatically created from descriptors that are contributed to the extension point `org.eclipse.net4j.db.dbAdapters`.

      In standalone scenarios the needed adapter instances must be registered with the `adapter registry` manually.

    - #### batched

          public static BatchedStatement batched​(java.sql.PreparedStatement delegate,
                                                 int batchSize)
                                          throws DBException

      Throws:
        `DBException`
      Since:
        4.5

    - #### close

          public static java.lang.Exception close​(java.sql.ResultSet resultSet)

    - #### close

          public static java.lang.Exception close​(java.sql.Statement statement)

    - #### close

          public static java.lang.Exception close​(java.sql.Connection connection)

    - #### isOptional

          public static boolean isOptional​(IDBElement element)

      Since:
        4.6

    - #### setOptional

          public static boolean setOptional​(IDBElement element,
                                            boolean optional)

      Since:
        4.6

    - #### setAutoCommit

          public static boolean setAutoCommit​(java.sql.Connection connection,
                                              boolean autoCommit)

      Since:
        4.2

    - #### rollbackSilently

          public static java.lang.Exception rollbackSilently​(java.sql.Connection connection)

      Since:
        4.2

    - #### getAllSchemaTableNames

          @Deprecated
          public static java.util.List<java.lang.String> getAllSchemaTableNames​(java.sql.Connection connection)

      Deprecated.
      As of 4.2 use `getAllSchemaNames(Connection)`.
      Since:
        3.0

    - #### getAllSchemaTableNames

          @Deprecated
          public static java.util.List<java.lang.String> getAllSchemaTableNames​(java.sql.DatabaseMetaData metaData)

      Deprecated.
      As of 4.2 use `getAllSchemaNames(DatabaseMetaData)`.
      Since:
        3.0

    - #### getAllSchemaNames

          public static java.util.List<java.lang.String> getAllSchemaNames​(java.sql.Connection connection)

      Since:
        4.2

    - #### getAllSchemaNames

          public static java.util.Set<java.lang.String> getAllSchemaNames​(java.sql.DatabaseMetaData metaData)

      Since:
        4.2

    - #### getAllTableNames

          public static java.util.List<java.lang.String> getAllTableNames​(java.sql.Connection connection,
                                                                          java.lang.String dbName)

    - #### dropAllTables

          public static java.util.List<java.lang.Exception> dropAllTables​(java.sql.Connection connection,
                                                                          java.lang.String dbName)

      Since:
        4.0

    - #### asInt

          public static int asInt​(java.lang.Object value)

      Since:
        4.2

    - #### asLong

          public static long asLong​(java.lang.Object value)

      Since:
        4.2

    - #### selectMinimumInt

          public static int selectMinimumInt​(java.sql.Connection connection,
                                             IDBField field,
                                             java.lang.String... where)
                                      throws DBException

      Throws:
        `DBException`
      Since:
        3.0

    - #### selectMinimumLong

          public static long selectMinimumLong​(java.sql.Connection connection,
                                               IDBField field,
                                               java.lang.String... where)
                                        throws DBException

      Throws:
        `DBException`
      Since:
        3.0

    - #### selectMaximumInt

          public static int selectMaximumInt​(java.sql.Connection connection,
                                             IDBField field,
                                             java.lang.String... where)
                                      throws DBException

      Throws:
        `DBException`
      Since:
        3.0

    - #### selectMaximumLong

          public static long selectMaximumLong​(java.sql.Connection connection,
                                               IDBField field,
                                               java.lang.String... where)
                                        throws DBException

      Throws:
        `DBException`
      Since:
        3.0

    - #### execute

          public static <T> T execute​(IDBConnectionProvider connectionProvider,
                                      DBUtil.RunnableWithConnection<T> runnable)

      Since:
        4.2

    - #### execute

          public static void execute​(java.sql.Connection connection,
                                     java.lang.CharSequence sql)

      Since:
        4.2

    - #### executeBatch

          public static void executeBatch​(java.sql.PreparedStatement stmt,
                                          int counter)

      Since:
        4.1

    - #### executeBatch

          public static void executeBatch​(java.sql.PreparedStatement stmt,
                                          int counter,
                                          boolean checkExactlyOne)

      Since:
        4.1

    - #### update

          public static int update​(java.sql.Connection connection,
                                   java.lang.String sql)

    - #### update

          public static int update​(java.sql.PreparedStatement stmt,
                                   boolean exactlyOne)
                            throws java.sql.SQLException

      Execute update on the given prepared statement and handle common cases of return values.
      Parameters:
        `stmt` - the prepared statement
        `exactlyOne` - if `true`, the update count is checked to be `1`. Else the update result is only checked so that the update was successful (i.e. result code != Statement.EXECUTE_FAILED).
      Returns:
        the update count / execution result as returned by `PreparedStatement.executeUpdate()`. Can be used by the caller to perform more advanced checks.
      Throws:
        `java.sql.SQLException` - if `PreparedStatement.executeUpdate()` throws it.
        `java.lang.IllegalStateException` - if the check indicated by `excatlyOne` indicates an error.
      Since:
        4.0

    - #### clearTable

          public static int clearTable​(java.sql.Connection connection,
                                       IDBTable table)

      Since:
        4.1

    - #### clearTable

          public static int clearTable​(java.sql.Connection connection,
                                       java.lang.String tableName)

      Since:
        4.1

    - #### select

          public static int select​(java.sql.Connection connection,
                                   IDBRowHandler rowHandler,
                                   java.lang.String where,
                                   IDBField... fields)
                            throws DBException

      Throws:
        `DBException`

    - #### select

          public static int select​(java.sql.Connection connection,
                                   IDBRowHandler rowHandler,
                                   IDBField... fields)
                            throws DBException

      Throws:
        `DBException`

    - #### select

          public static java.lang.Object[] select​(java.sql.Connection connection,
                                                  java.lang.String where,
                                                  IDBField... fields)
                                           throws DBException

      Throws:
        `DBException`

    - #### getRowCount

          public static int getRowCount​(java.sql.ResultSet resultSet)
                                 throws DBException

      Returns the number of rows contained in the given result set.

      The `statement` of the result set must have been created with `TYPE_SCROLL_INSENSITIVE`.

      Throws:
        `DBException`
      Since:
        4.0

    - #### getRowCount

          public static int getRowCount​(java.sql.Connection connection,
                                        java.lang.String tableName)
                                 throws DBException

      Returns the number of rows contained in the given table.
      Throws:
        `DBException`
      Since:
        4.5

    - #### serializeTable

          public static void serializeTable​(org.eclipse.net4j.util.io.ExtendedDataOutput out,
                                            java.sql.Connection connection,
                                            IDBTable table,
                                            java.lang.String tableAlias,
                                            java.lang.String sqlSuffix)
                                     throws DBException,
                                            java.io.IOException

      Throws:
        `DBException`
        `java.io.IOException`
      Since:
        3.0

    - #### serializeTable

          public static void serializeTable​(org.eclipse.net4j.util.io.ExtendedDataOutput out,
                                            java.sql.Connection connection,
                                            IDBTable table,
                                            java.lang.String tableAlias,
                                            java.lang.String sqlSuffix,
                                            DBUtil.SerializeRowHandler handler)
                                     throws DBException,
                                            java.io.IOException

      Throws:
        `DBException`
        `java.io.IOException`
      Since:
        4.1

    - #### deserializeTable

          public static void deserializeTable​(org.eclipse.net4j.util.io.ExtendedDataInput in,
                                              java.sql.Connection connection,
                                              IDBTable table,
                                              org.eclipse.net4j.util.om.monitor.OMMonitor monitor)
                                       throws java.io.IOException

      Throws:
        `java.io.IOException`
      Since:
        4.0

    - #### deserializeTable

          public static void deserializeTable​(org.eclipse.net4j.util.io.ExtendedDataInput in,
                                              java.sql.Connection connection,
                                              IDBTable table,
                                              org.eclipse.net4j.util.om.monitor.OMMonitor monitor,
                                              DBUtil.DeserializeRowHandler handler)
                                       throws java.io.IOException

      Throws:
        `java.io.IOException`
      Since:
        4.1

    - #### trace

          public static java.lang.String trace​(java.lang.String sql)

      Since:
        3.0

    - #### isTracerEnabled

          public static boolean isTracerEnabled()

      Since:
        4.2