JDBCRepositoryBuilder (Carbonado 1.2.3 API)

java.lang.Object
- com.amazon.carbonado.spi.AbstractRepositoryBuilder
- - com.amazon.carbonado.repo.jdbc.JDBCRepositoryBuilder

All Implemented Interfaces:

RepositoryBuilder
```
public class JDBCRepositoryBuilder
extends AbstractRepositoryBuilder
```
Builds a repository instance backed by a JDBC accessible database. JDBCRepository is not independent of the underlying database schema, and so it requires matching tables and columns in the database. It will not alter or create tables. Use the Alias annotation to control precisely which tables and columns must be matched up.
Note: The current JDBC repository implementation makes certain assumptions about the database it is accessing. It must support transactions and multiple statements per connection. If it doesn't support savepoints, then nested transactions are faked -- rollback of inner transaction will appear to do nothing.
The following extra capabilities are supported:
Author:

Brian S O'Neill, bcastill, Adam D Bradley

Constructor Summary

Constructors
Constructor and Description

JDBCRepositoryBuilder()

Constructors
Constructor and Description
`JDBCRepositoryBuilder()`

Method Summary

Methods
Modifier and Type	Method and Description
`Repository`	`build(java.util.concurrent.atomic.AtomicReference<Repository> rootRef)` Builds a repository instance.
`void`	`errorCheck(java.util.Collection<java.lang.String> messages)` This method is called by assertReady, and subclasses must override to perform custom checks.
`java.lang.String`	`getCatalog()` Returns the optional catalog to search for metadata.
`javax.sql.DataSource`	`getDataSource()` Returns the source of JDBC connections, which defaults to a non-pooling source if driver class, driver URL, username, and password are all supplied.
`boolean`	`getDataSourceCloseOnShutdown()` Returns true if DataSource is closed when the repository is closed or shutdown.
`boolean`	`getDataSourceLogging()` Returns true if debug logging is enabled.
`java.lang.Integer`	`getDefaultFetchSize()` Returns the default fetch size when running queries, or null if driver default is used instead.
`java.lang.String`	`getDriverClassName()` Returns the driver class name, which may be null if a DataSource was provided.
`java.lang.String`	`getDriverURL()` Returns the connection URL, which may be null if a DataSource was provided.
`java.lang.String`	`getName()` Returns the name of the repository.
`java.lang.String`	`getPassword()` Returns the optional password to use with DataSource.
`java.lang.String`	`getSchema()` Returns the optional schema to search for metadata.
`java.lang.String`	`getSequenceSelectStatement()` Returns the native sequence select statement, which is null if the default is chosen.
`java.lang.String`	`getUserName()` Returns the optional username to use with DataSource.
`boolean`	`isForceStoredSequence()` Returns true if native sequences should not be used.
`boolean`	`isMaster()` Returns true if repository should assume the role of master, which is true by default.
`void`	`setAutoVersioningEnabled(boolean enabled, java.lang.String className)` By default, JDBCRepository assumes that `version numbers` are initialized and incremented by triggers installed on the database.
`void`	`setCatalog(java.lang.String catalog)` Optionally set the catalog to search for metadata.
`void`	`setDataSource(javax.sql.DataSource dataSource)` Set the source of JDBC connections, overriding any configuration supported by these methods: `setDriverClassName(java.lang.String)` `setDriverURL(java.lang.String)` `setUserName(java.lang.String)` `setPassword(java.lang.String)`
`void`	`setDataSourceCloseOnShutdown(boolean b)` Pass true to cause the DataSource to be closed when the repository is closed or shutdown.
`void`	`setDataSourceLogging(boolean b)` Pass true to enable debug logging.
`void`	`setDefaultFetchSize(java.lang.Integer size)` Set the default fetch size when running queries.
`void`	`setDriverClassName(java.lang.String driverClassName)` Set the JDBC driver class name, which is required if a DataSource was not provided.
`void`	`setDriverURL(java.lang.String url)` Set the JDBC connection URL, which is required if a DataSource was not provided.
`void`	`setForceStoredSequence(boolean forceStoredSequence)` By default, native sequences are used if supported.
`void`	`setMaster(boolean b)` Set to false if repository should not assume the role of master.
`void`	`setName(java.lang.String name)` Set name for the repository, which is required.
`void`	`setPassword(java.lang.String password)` Optionally set the password to use with DataSource.
`void`	`setPrimaryKeyCheckDisabled(boolean primaryKeyCheckDisabled)` By default, JDBCRepository makes sure that every declared primary key in the database table for a Storable lines up with a declared PrimaryKey or AlternateKey.
`void`	`setSchema(java.lang.String schema)` Optionally set the schema to search for metadata.
`void`	`setSequenceSelectStatement(java.lang.String sequenceSelectStatement)` Override the default native sequence select statement with a printf.
`void`	`setSuppressReload(boolean suppress, java.lang.String className)` By default, JDBCRepository reloads Storables after every insert or update.
`void`	`setUserName(java.lang.String username)` Optionally set the username to use with DataSource.

Methods inherited from class com.amazon.carbonado.spi.AbstractRepositoryBuilder
addTriggerFactory, assertReady, build, getTriggerFactories, removeTriggerFactory

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - JDBCRepositoryBuilder
```
public JDBCRepositoryBuilder()
```
- Method Detail
  - build
```
public Repository build(java.util.concurrent.atomic.AtomicReference<Repository> rootRef)
                 throws RepositoryException
```
    Description copied from interface: RepositoryBuilder
    
    Builds a repository instance.
    If the repository is being wrapped by a parent repository, the child repository will need to know this fact for some operations to work correctly. Since the parent repository is not built yet, a reference is used instead.
    
    Parameters:
    rootRef - reference to root parent repository, to be set by parent repository upon being built
    
    Throws:
    
    ConfigurationException - if there is a problem in the builder's configuration
    
    RepositoryException - if there is a general problem opening the repository
  - getName
```
public java.lang.String getName()
```
    Description copied from interface: RepositoryBuilder
    
    Returns the name of the repository.
  - setName
```
public void setName(java.lang.String name)
```
    Description copied from interface: RepositoryBuilder
    
    Set name for the repository, which is required.
  - isMaster
```
public boolean isMaster()
```
    Description copied from interface: RepositoryBuilder
    
    Returns true if repository should assume the role of master, which is true by default. Repositories that link different repositories together will designate only one as the master.
    A master repository is responsible for version and sequence properties. For insert operations, a master repository must set these properties if they are uninitialized. For updates, the version property is checked to see if an OptimisticLockException should be thrown.
    
    See Also:
    ReplicatedRepositoryBuilder
  - setMaster
```
public void setMaster(boolean b)
```
    Description copied from interface: RepositoryBuilder
    
    Set to false if repository should not assume the role of master. By default, this option is true. Repositories that link different repositories together will designate only one as the master.
    A master repository is responsible for version and sequence properties. For insert operations, a master repository must set these properties if they are uninitialized. For updates, the version property is checked to see if an OptimisticLockException should be thrown.
    
    See Also:
    ReplicatedRepositoryBuilder
  - setDataSource
```
public void setDataSource(javax.sql.DataSource dataSource)
```
    Set the source of JDBC connections, overriding any configuration supported by these methods:
  - getDataSource
```
public javax.sql.DataSource getDataSource()
                                   throws ConfigurationException
```
    Returns the source of JDBC connections, which defaults to a non-pooling source if driver class, driver URL, username, and password are all supplied.
    
    Throws:
    
    ConfigurationException - if driver class wasn't found
  - setDataSourceCloseOnShutdown
```
public void setDataSourceCloseOnShutdown(boolean b)
```
    Pass true to cause the DataSource to be closed when the repository is closed or shutdown. By default, this option is false.
    
    Since:
    
    1.2
  - getDataSourceCloseOnShutdown
```
public boolean getDataSourceCloseOnShutdown()
```
    Returns true if DataSource is closed when the repository is closed or shutdown. By default, this option is false.
    
    Since:
    
    1.2
  - setDataSourceLogging
```
public void setDataSourceLogging(boolean b)
```
    Pass true to enable debug logging. By default, it is false.
    
    See Also:
    LoggingDataSource
  - getDataSourceLogging
```
public boolean getDataSourceLogging()
```
    Returns true if debug logging is enabled.
    
    See Also:
    LoggingDataSource
  - setCatalog
```
public void setCatalog(java.lang.String catalog)
```
    Optionally set the catalog to search for metadata.
  - getCatalog
```
public java.lang.String getCatalog()
```
    Returns the optional catalog to search for metadata.
  - setSchema
```
public void setSchema(java.lang.String schema)
```
    Optionally set the schema to search for metadata.
  - getSchema
```
public java.lang.String getSchema()
```
    Returns the optional schema to search for metadata.
  - setDriverClassName
```
public void setDriverClassName(java.lang.String driverClassName)
```
    Set the JDBC driver class name, which is required if a DataSource was not provided.
  - getDriverClassName
```
public java.lang.String getDriverClassName()
```
    Returns the driver class name, which may be null if a DataSource was provided.
  - setDriverURL
```
public void setDriverURL(java.lang.String url)
```
    Set the JDBC connection URL, which is required if a DataSource was not provided.
  - getDriverURL
```
public java.lang.String getDriverURL()
```
    Returns the connection URL, which may be null if a DataSource was provided.
  - setUserName
```
public void setUserName(java.lang.String username)
```
    Optionally set the username to use with DataSource.
  - getUserName
```
public java.lang.String getUserName()
```
    Returns the optional username to use with DataSource.
  - setPassword
```
public void setPassword(java.lang.String password)
```
    Optionally set the password to use with DataSource.
  - getPassword
```
public java.lang.String getPassword()
```
    Returns the optional password to use with DataSource.
  - setDefaultFetchSize
```
public void setDefaultFetchSize(java.lang.Integer size)
```
    Set the default fetch size when running queries. Pass null to let driver use its own default.
    
    Since:
    
    1.2
  - getDefaultFetchSize
```
public java.lang.Integer getDefaultFetchSize()
```
    Returns the default fetch size when running queries, or null if driver default is used instead.
    
    Since:
    
    1.2
  - setAutoVersioningEnabled
```
public void setAutoVersioningEnabled(boolean enabled,
                            java.lang.String className)
```
    By default, JDBCRepository assumes that version numbers are initialized and incremented by triggers installed on the database. Enabling automatic versioning here causes the JDBCRepository to manage these operations itself.
    
    Parameters:
    enabled - true to enable, false to disable
    className - name of Storable type to enable automatic version management on; pass null to enable all
    Since:
    
    1.2
  - setSuppressReload
```
public void setSuppressReload(boolean suppress,
                     java.lang.String className)
```
    By default, JDBCRepository reloads Storables after every insert or update. This ensures that any applied defaults or triggered changes are available to the Storable. If the database has no such defaults or triggers, suppressing reload can improve performance.
    Note: If Storable has a version property and auto versioning is not enabled, or if the Storable has any automatic properties, the Storable might still be reloaded.
    
    Parameters:
    suppress - true to suppress, false to unsuppress
    className - name of Storable type to suppress reload for; pass null to suppress all
    Since:
    
    1.1.3
  - getSequenceSelectStatement
```
public java.lang.String getSequenceSelectStatement()
```
    Returns the native sequence select statement, which is null if the default is chosen.
    
    Since:
    
    1.2
  - setSequenceSelectStatement
```
public void setSequenceSelectStatement(java.lang.String sequenceSelectStatement)
```
    Override the default native sequence select statement with a printf. For example, "SELECT %s.NEXTVAL FROM DUAL".
    
    Since:
    
    1.2
  - isForceStoredSequence
```
public boolean isForceStoredSequence()
```
    Returns true if native sequences should not be used.
    
    Since:
    
    1.2
  - setForceStoredSequence
```
public void setForceStoredSequence(boolean forceStoredSequence)
```
    By default, native sequences are used if supported. Otherwise, a table named "CARBONADO_SEQUENCE" or "CARBONADO_SEQUENCES" is used instead to hold sequence values. When forced, the table is always used instead of native sequences.
    
    Since:
    
    1.2
  - setPrimaryKeyCheckDisabled
```
public void setPrimaryKeyCheckDisabled(boolean primaryKeyCheckDisabled)
```
    By default, JDBCRepository makes sure that every declared primary key in the database table for a Storable lines up with a declared PrimaryKey or AlternateKey. This is not always the desired behavior; for example, you may have a table which uses a bigint for its actual primary key but uses another column with a unique index as the "primary" key from the application's point of view. Setting this value to true allows this check to fail gracefully instead of throwing a MismatchException.
    
    Since:
    
    1.2
  - errorCheck
```
public void errorCheck(java.util.Collection<java.lang.String> messages)
                throws ConfigurationException
```
    Description copied from class: AbstractRepositoryBuilder
    
    This method is called by assertReady, and subclasses must override to perform custom checks. Be sure to call super.errorCheck as well.
    
    Overrides:
    
    errorCheck in class AbstractRepositoryBuilder
    
    Parameters:
    messages - add any error messages to this list
    
    Throws:
    
    ConfigurationException - if error checking indirectly caused another exception

Class JDBCRepositoryBuilder

Constructor Summary

Method Summary

Methods inherited from class com.amazon.carbonado.spi.AbstractRepositoryBuilder

Methods inherited from class java.lang.Object

Constructor Detail

JDBCRepositoryBuilder

Method Detail

build

getName

setName

isMaster

setMaster

setDataSource

getDataSource

setDataSourceCloseOnShutdown

getDataSourceCloseOnShutdown

setDataSourceLogging

getDataSourceLogging

setCatalog

getCatalog

setSchema

getSchema

setDriverClassName

getDriverClassName

setDriverURL

getDriverURL

setUserName

getUserName

setPassword

getPassword

setDefaultFetchSize

getDefaultFetchSize

setAutoVersioningEnabled

setSuppressReload

getSequenceSelectStatement

setSequenceSelectStatement

isForceStoredSequence

setForceStoredSequence

setPrimaryKeyCheckDisabled

errorCheck