com.univocity.api.entity.jdbc
Class JdbcEntityConfiguration

java.lang.Object
  extended by com.univocity.api.entity.Configuration
      extended by com.univocity.api.entity.jdbc.JdbcEntityConfiguration

public final class JdbcEntityConfiguration
extends Configuration

This class provides configuration options for JDBC data entities. Instances are accessible through a JdbcDataStoreConfiguration configuration object.

Author:
uniVocity Software Pty Ltd - dev@univocity.com
See Also:
DatabaseCapabilities, BaseJdbcEntityConfiguration, JdbcDataStoreConfiguration

Method Summary
 DefaultEntityField configureField(String fieldName)
          Configures the properties of a field in this entity.
protected  void copyDefaultsFrom(Configuration defaultsObject)
          Applies default values to undefined settings using a Configuration object.
 int getBatchSize()
          Obtains the number of rows to be persisted in a single batch execution.
 int getFetchSize()
          Obtains the number of rows to return for an open ResultSet in a each each trip to the database.
 SqlProducer getSqlProducer()
          Obtains the custom SqlProducer responsible for generating user-specific SQL statements when reading or writing data to this entity.
 boolean isParameterConversionEnabled()
          Indicates whether values passed to prepared statements will be converted to expected database type by uniVocity.
 void retrieveGeneratedKeysUsingNumericColumns(String processIdentificationColumn, String trackingColumn, String generatedKeyColumn, String... otherGeneratedColumnsToRetrieve)
          Specifies auto-generated keys should be extracted using two additional columns, assigned to uniVocity, for tracking rows in a batch of insert operations.
 void retrieveGeneratedKeysUsingQuery(String generatedKeyColumn, String... otherGeneratedColumnsToRetrieve)
          Specifies auto-generated keys should be extracted using a query after a batch of row inserts took place.
 void retrieveGeneratedKeysUsingStatement(boolean insertInBatch)
          Specifies auto-generated keys should be extracted using the JDBC driver's Statement.getGeneratedKeys() method when new rows are inserted into this entity.
 void retrieveGeneratedKeysUsingStringColumn(String trackingColumn, String generatedKeyColumn, String... otherGeneratedColumnsToRetrieve)
          Specifies auto-generated keys should be extracted using an additional column, assigned to uniVocity, for tracking rows in a batch of insert operations.
 void setBatchSize(int batchSize)
          Defines the number of rows to be persisted in a single batch execution.
 void setFetchSize(int fetchSize)
          Defines the number of rows to return for an open ResultSet in a each each trip to the database.
 void setParameterConversionEnabled(boolean parameterConversionEnabled)
          Attempts to convert values passed to prepared statements to the expected database type.
 void setSqlProducer(SqlProducer sqlProducer)
          Defines a custom SqlProducer responsible for generating user-specific SQL statements when reading or writing data to this entity.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

copyDefaultsFrom

protected final void copyDefaultsFrom(Configuration defaultsObject)
Applies default values to undefined settings using a Configuration object.

Parameters:
defaultsObject - a configuration object from where to obtain default settings.

isParameterConversionEnabled

public boolean isParameterConversionEnabled()
Indicates whether values passed to prepared statements will be converted to expected database type by uniVocity. This might be required for some JDBC drivers that won't convert values automatically when PreparedStatement.setObject(int, Object) is used. For example, on insertion if a field of type Integer is written, this setting will make uniVocity try to convert the value and then invoke PreparedStatement.setInt(int, int).

Returns:
parameterConversionEnabled indicates whether uniVocity will convert parameter values when calling prepared statements.

setParameterConversionEnabled

public void setParameterConversionEnabled(boolean parameterConversionEnabled)
Attempts to convert values passed to prepared statements to the expected database type. This might be required for some JDBC drivers that won't convert values automatically when PreparedStatement.setObject(int, Object) is used. For example, on insertion if a field of type Integer is written, this setting will make uniVocity try to convert the value and then invoke PreparedStatement.setInt(int, int).

Parameters:
parameterConversionEnabled - indicates whether to convert parameter values on prepared statements.

getBatchSize

public final int getBatchSize()
Obtains the number of rows to be persisted in a single batch execution.

This setting has an effect only when DatabaseCapabilities.isBatchSupported() evaluates to true.

Batching database operations greatly improves performance in general, but you might want to adjust the batch size to better control memory usage and batch duration.

Defaults to 10,000 rows

Returns:
the batch size to use when persisting values into the configured JDBC data entity.
See Also:
DatabaseCapabilities

setBatchSize

public final void setBatchSize(int batchSize)
Defines the number of rows to be persisted in a single batch execution.

This setting has an effect only when DatabaseCapabilities.isBatchSupported() evaluates to true.

Batching database operations greatly improves performance in general, but you might want to adjust the batch size to better control memory usage and batch duration.

Parameters:
batchSize - the batch size to use when persisting values into the configured JDBC data entity.
See Also:
DatabaseCapabilities

retrieveGeneratedKeysUsingStatement

public final void retrieveGeneratedKeysUsingStatement(boolean insertInBatch)
Specifies auto-generated keys should be extracted using the JDBC driver's Statement.getGeneratedKeys() method when new rows are inserted into this entity.

Parameters:
insertInBatch - a flag indicating whether to perform insert operations in batch or not. This has the following implications:
  • if true: insert operations will be batched and generated keys will be returned in a single ResultSet by your JDBC driver.
    Your JDBC driver might not support that. If that's the case and you need to have batch insertion for performance reasons, you might want to update your JDBC driver, or if it is not possible, use one of the following auto-generated key retrieval strategies:
  • if false: insert operations will not be batched. For each row to insert, a single insert statement will be executed, an the auto-generated key for the inserted row will be read using Statement.getGeneratedKeys().
    As this involves many database roundtrips, performance is much worse than inserting in batch and then extracting all generated keys in one go.
    If you are experiencing performance issues you might want to study the possibility of using the alternative strategies for generated key extraction provided by this class.
See Also:
Statement

retrieveGeneratedKeysUsingQuery

public final void retrieveGeneratedKeysUsingQuery(String generatedKeyColumn,
                                                  String... otherGeneratedColumnsToRetrieve)
Specifies auto-generated keys should be extracted using a query after a batch of row inserts took place. You can safely use this if your transaction isolation level is set to Connection.TRANSACTION_SERIALIZABLE.

This strategy performs the following sequence of operations to fetch generated keys:

The transaction isolation level used by your JDBC data entities is configured in JdbcDataStoreConfiguration.setTransactionIsolationLevel(int).

If you can't use the Connection.TRANSACTION_SERIALIZABLE transaction isolation level, then this strategy have data consistency implications you must be aware of:

Parameters:
generatedKeyColumn - the name of the auto-generated key column of this table.
otherGeneratedColumnsToRetrieve - the names of other columns with auto-generated values you are interested in retrieving as well.

retrieveGeneratedKeysUsingStringColumn

public final void retrieveGeneratedKeysUsingStringColumn(String trackingColumn,
                                                         String generatedKeyColumn,
                                                         String... otherGeneratedColumnsToRetrieve)
Specifies auto-generated keys should be extracted using an additional column, assigned to uniVocity, for tracking rows in a batch of insert operations.

This strategy performs the following sequence of operations to fetch generated keys:

Parameters:
trackingColumn - the name of the column used by uniVocity to provide row tracking information.
generatedKeyColumn - the name of the auto-generated key column of this table.
otherGeneratedColumnsToRetrieve - the names of other columns with auto-generated values you are interested in retrieving as well.

retrieveGeneratedKeysUsingNumericColumns

public final void retrieveGeneratedKeysUsingNumericColumns(String processIdentificationColumn,
                                                           String trackingColumn,
                                                           String generatedKeyColumn,
                                                           String... otherGeneratedColumnsToRetrieve)
Specifies auto-generated keys should be extracted using two additional columns, assigned to uniVocity, for tracking rows in a batch of insert operations.

This strategy performs the following sequence of operations to fetch generated keys:

Parameters:
processIdentificationColumn - the name of the column used by uniVocity to identify the batch process.
trackingColumn - the name of the column used by uniVocity to identify the index of each row added to the batch.
generatedKeyColumn - the name of the auto-generated key column of this table.
otherGeneratedColumnsToRetrieve - the names of other columns with auto-generated values you are interested in retrieving as well.

getSqlProducer

public final SqlProducer getSqlProducer()
Obtains the custom SqlProducer responsible for generating user-specific SQL statements when reading or writing data to this entity.

Returns:
the custom SqlProducer

setSqlProducer

public final void setSqlProducer(SqlProducer sqlProducer)
Defines a custom SqlProducer responsible for generating user-specific SQL statements when reading or writing data to this entity.

Parameters:
sqlProducer - the SqlProducer

getFetchSize

public final int getFetchSize()
Obtains the number of rows to return for an open ResultSet in a each each trip to the database.

uniVocity passes this value directly to your database driver using Statement.setFetchSize(int).

For performance reasons, you might want to adjust the fetch size to reflect the common number of rows returned for this entity. A big fetch size number might consume too many resources and will be excessive for a small number of records. A small fetch size for too many rows will cause slowness (e.g. a fetch size of 100 to read 10,000 rows and will generate 100 roundtrips to the database).

Defaults to 10,000 rows

Returns:
the fetch size to use when reading values from the configured JDBC data entity.
See Also:
Statement

setFetchSize

public final void setFetchSize(int fetchSize)
Defines the number of rows to return for an open ResultSet in a each each trip to the database.

uniVocity passes this value directly to your database driver using Statement.setFetchSize(int).

For performance reasons, you might want to adjust the fetch size to reflect the common number of rows returned for this entity. A big fetch size number might consume too many resources and will be excessive for a small number of records. A small fetch size for too many rows will cause slowness (e.g. a fetch size of 100 to read 10,000 rows and will generate 100 roundtrips to the database).

Parameters:
fetchSize - the fetch size to use when reading values from the configured JDBC data entity.
This parameter is not validated as some database drivers accept special settings for the fetch size, such as Integer.MIN_VALUE.
See Also:
Statement

configureField

public DefaultEntityField configureField(String fieldName)
Configures the properties of a field in this entity. uniVocity autodetects column metadata of JDBC entities, but it may not always obtain all the information it needs from the JDBC driver. For example, it can't detect autogenerated columns where values are produced by a trigger (e.g. Oracle, prior to version 12, did not have an IDENTITY type)

Parameters:
fieldName - the name of the field to be configured explicitly
Returns:
a DefaultEntityField object with properties that can be manually set for the given field.


Copyright © 2015 uniVocity Software Pty Ltd. All rights reserved.