com.github.susom.database

Class DatabaseProvider

java.lang.Object

com.github.susom.database.DatabaseProvider

All Implemented Interfaces:

Supplier<Database>

public final class DatabaseProvider
extends Object
implements Supplier<Database>

This is a lazy provider for Database instances. It helps avoid allocating connection or transaction resources until (or if) we actually need a Database. As a consequence of this laziness, the underlying resources require explicit cleanup by calling either commitAndClose() or rollbackAndClose().

Author:

garricko

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DatabaseProvider.Builder This builder is immutable, so setting various options does not affect the previous instance.
static class	DatabaseProvider.Pool

Constructor Summary

Constructors

Constructor and Description
DatabaseProvider(Supplier<Connection> connectionProvider, Options options)

Method Summary

Modifier and Type	Method and Description
void	commitAndClose()
static DatabaseProvider.Pool	createPool(Config config)
DatabaseProvider.Builder	fakeBuilder()
static DatabaseProvider.Builder	fromDriverManager(Config config)
static DatabaseProvider.Builder	fromDriverManager(String url) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromDriverManager(String url, Flavor flavor) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromDriverManager(String url, Flavor flavor, Properties info) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromDriverManager(String url, Flavor flavor, String user, String password) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromDriverManager(String url, Properties info) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromDriverManager(String url, String user, String password) Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.
static DatabaseProvider.Builder	fromJndi(Context context, String lookupKey, Flavor flavor) Builder method to create and initialize an instance of this class using a JNDI resource.
static DatabaseProvider.Builder	fromPool(DatabaseProvider.Pool pool) Use an externally configured DataSource, Flavor, and optionally a shutdown hook.
static DatabaseProvider.Builder	fromProperties(Properties properties) Configure the database from up to five properties read from the provided properties:
static DatabaseProvider.Builder	fromProperties(Properties properties, String propertyPrefix) Configure the database from up to five properties read from the provided properties:
static DatabaseProvider.Builder	fromPropertyFile(String filename) Configure the database from up to five properties read from a file:
static DatabaseProvider.Builder	fromPropertyFile(String filename, CharsetDecoder decoder) Configure the database from up to five properties read from a file:
static DatabaseProvider.Builder	fromPropertyFile(String filename, String propertyPrefix) Configure the database from up to five properties read from a file:
static DatabaseProvider.Builder	fromPropertyFile(String filename, String propertyPrefix, CharsetDecoder decoder) Configure the database from up to five properties read from a file:
static DatabaseProvider.Builder	fromPropertyFileOrSystemProperties(String filename) Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):
static DatabaseProvider.Builder	fromPropertyFileOrSystemProperties(String filename, CharsetDecoder decoder) Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):
static DatabaseProvider.Builder	fromPropertyFileOrSystemProperties(String filename, String propertyPrefix) Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):
static DatabaseProvider.Builder	fromPropertyFileOrSystemProperties(String filename, String propertyPrefix, CharsetDecoder decoder) Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):
static DatabaseProvider.Builder	fromSystemProperties() Configure the database from up to five system properties:
static DatabaseProvider.Builder	fromSystemProperties(String propertyPrefix) Configure the database from up to five system properties:
Database	get()
static DatabaseProvider.Builder	pooledBuilder(Config config) Configure the database from the following properties read from the provided configuration:
void	rollbackAndClose()
void	transact(DbCode code)
void	transact(DbCodeTx code)
<T> T	transactReturning(DbCodeTyped<T> code)

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseProvider

public DatabaseProvider(Supplier<Connection> connectionProvider,
                        Options options)

Method Detail

pooledBuilder

@CheckReturnValue
public static DatabaseProvider.Builder pooledBuilder(Config config)

Configure the database from the following properties read from the provided configuration:

   database.url=...       Database connect string (required)
   database.user=...      Authenticate as this user (optional if provided in url)
   database.password=...  User password (optional if user and password provided in
                          url; prompted on standard input if user is provided and
                          password is not)
   database.pool.size=... How many connections in the connection pool (default 10).
   database.driver.class  The driver to initialize with Class.forName(). This will
                          be guessed from the database.url if not provided.
   database.flavor        One of the enumerated values in Flavor. If this
                          is not provided the flavor will be guessed based on the
                          value for database.url, if possible.
 

The database flavor will be guessed based on the URL.

A database pool will be created using HikariCP.

Be sure to retain a copy of the builder so you can call close() later to destroy the pool. You will most likely want to register a JVM shutdown hook to make sure this happens. See VertxServer.java in the demo directory for an example of how to do this.

fromPool

@CheckReturnValue
public static DatabaseProvider.Builder fromPool(DatabaseProvider.Pool pool)

Use an externally configured DataSource, Flavor, and optionally a shutdown hook. The shutdown hook may be null if you don't want calls to Builder.close() to attempt any shutdown. The DataSource and Flavor are mandatory.

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method. The url parameter will be inspected to determine the Flavor for this database.

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url,
                                                                           Flavor flavor)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.

Parameters:

flavor - use this flavor rather than guessing based on the url

fromDriverManager

public static DatabaseProvider.Builder fromDriverManager(Config config)

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url,
                                                                           Properties info)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method. The url parameter will be inspected to determine the Flavor for this database.

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url,
                                                                           Flavor flavor,
                                                                           Properties info)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.

Parameters:

flavor - use this flavor rather than guessing based on the url

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url,
                                                                           String user,
                                                                           String password)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method. The url parameter will be inspected to determine the Flavor for this database.

fromDriverManager

@CheckReturnValue
public static DatabaseProvider.Builder fromDriverManager(String url,
                                                                           Flavor flavor,
                                                                           String user,
                                                                           String password)

Builder method to create and initialize an instance of this class using the JDBC standard DriverManager method.

Parameters:

flavor - use this flavor rather than guessing based on the url

fromJndi

@CheckReturnValue
public static DatabaseProvider.Builder fromJndi(Context context,
                                                                  String lookupKey,
                                                                  Flavor flavor)

Builder method to create and initialize an instance of this class using a JNDI resource. To use this method you must explicitly indicate what Flavor of database we are dealing with.

fromPropertyFile

public static DatabaseProvider.Builder fromPropertyFile(String filename)

Configure the database from up to five properties read from a file:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

This will use the JVM default character encoding to read the property file.

Parameters:

filename - path to the properties file we will attempt to read

Throws:

DatabaseException - if the property file could not be read for any reason

fromPropertyFile

public static DatabaseProvider.Builder fromPropertyFile(String filename,
                                                        CharsetDecoder decoder)

Configure the database from up to five properties read from a file:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

filename - path to the properties file we will attempt to read

decoder - character encoding to use when reading the property file

Throws:

DatabaseException - if the property file could not be read for any reason

fromPropertyFile

public static DatabaseProvider.Builder fromPropertyFile(String filename,
                                                        String propertyPrefix)

Configure the database from up to five properties read from a file:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

This will use the JVM default character encoding to read the property file.

Parameters:

filename - path to the properties file we will attempt to read

propertyPrefix - if this is null or empty the properties above will be read; if a value is provided it will be prefixed to each property (exactly, so if you want to use "my.database.url" you must pass "my." as the prefix)

Throws:

DatabaseException - if the property file could not be read for any reason

fromPropertyFile

public static DatabaseProvider.Builder fromPropertyFile(String filename,
                                                        String propertyPrefix,
                                                        CharsetDecoder decoder)

Configure the database from up to five properties read from a file:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

filename - path to the properties file we will attempt to read

propertyPrefix - if this is null or empty the properties above will be read; if a value is provided it will be prefixed to each property (exactly, so if you want to use "my.database.url" you must pass "my." as the prefix)

decoder - character encoding to use when reading the property file

Throws:

DatabaseException - if the property file could not be read for any reason

fromProperties

public static DatabaseProvider.Builder fromProperties(Properties properties)

Configure the database from up to five properties read from the provided properties:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

properties - properties will be read from here

Throws:

DatabaseException - if the property file could not be read for any reason

fromProperties

public static DatabaseProvider.Builder fromProperties(Properties properties,
                                                      String propertyPrefix)

Configure the database from up to five properties read from the provided properties:

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

properties - properties will be read from here

propertyPrefix - if this is null or empty the properties above will be read; if a value is provided it will be prefixed to each property (exactly, so if you want to use "my.database.url" you must pass "my." as the prefix)

Throws:

DatabaseException - if the property file could not be read for any reason

fromPropertyFileOrSystemProperties

public static DatabaseProvider.Builder fromPropertyFileOrSystemProperties(String filename)

Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

This will use the JVM default character encoding to read the property file.

Parameters:

filename - path to the properties file we will attempt to read; if the file cannot be read for any reason (e.g. does not exist) a debug level log entry will be entered, but it will attempt to proceed using solely the system properties

fromPropertyFileOrSystemProperties

public static DatabaseProvider.Builder fromPropertyFileOrSystemProperties(String filename,
                                                                          CharsetDecoder decoder)

Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

filename - path to the properties file we will attempt to read; if the file cannot be read for any reason (e.g. does not exist) a debug level log entry will be entered, but it will attempt to proceed using solely the system properties

decoder - character encoding to use when reading the property file

fromPropertyFileOrSystemProperties

public static DatabaseProvider.Builder fromPropertyFileOrSystemProperties(String filename,
                                                                          String propertyPrefix)

Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

This will use the JVM default character encoding to read the property file.

Parameters:

filename - path to the properties file we will attempt to read; if the file cannot be read for any reason (e.g. does not exist) a debug level log entry will be entered, but it will attempt to proceed using solely the system properties

propertyPrefix - if this is null or empty the properties above will be read; if a value is provided it will be prefixed to each property (exactly, so if you want to use "my.database.url" you must pass "my." as the prefix)

fromPropertyFileOrSystemProperties

public static DatabaseProvider.Builder fromPropertyFileOrSystemProperties(String filename,
                                                                          String propertyPrefix,
                                                                          CharsetDecoder decoder)

Configure the database from up to five properties read from the specified properties file, or from the system properties (system properties will take precedence over the file):

   database.url=...      Database connect string (required)
   database.user=...     Authenticate as this user (optional if provided in url)
   database.password=... User password (optional if user and password provided in
                         url; prompted on standard input if user is provided and
                         password is not)
   database.flavor=...   What kind of database it is (optional, will guess based
                         on the url if this is not provided)
   database.driver=...   The Java class of the JDBC driver to load (optional, will
                         guess based on the flavor if this is not provided)
 

Parameters:

filename - path to the properties file we will attempt to read; if the file cannot be read for any reason (e.g. does not exist) a debug level log entry will be entered, but it will attempt to proceed using solely the system properties

propertyPrefix - if this is null or empty the properties above will be read; if a value is provided it will be prefixed to each property (exactly, so if you want to use "my.database.url" you must pass "my." as the prefix)

decoder - character encoding to use when reading the property file

fromSystemProperties

@CheckReturnValue
public static DatabaseProvider.Builder fromSystemProperties()

Configure the database from up to five system properties:

   -Ddatabase.url=...      Database connect string (required)
   -Ddatabase.user=...     Authenticate as this user (optional if provided in url)
   -Ddatabase.password=... User password (optional if user and password provided in
                           url; prompted on standard input if user is provided and
                           password is not)
   -Ddatabase.flavor=...   What kind of database it is (optional, will guess based
                           on the url if this is not provided)
   -Ddatabase.driver=...   The Java class of the JDBC driver to load (optional, will
                           guess based on the flavor if this is not provided)
 

fromSystemProperties

@CheckReturnValue
public static DatabaseProvider.Builder fromSystemProperties(String propertyPrefix)

Configure the database from up to five system properties:

   -D{prefix}database.url=...      Database connect string (required)
   -D{prefix}database.user=...     Authenticate as this user (optional if provided in url)
   -D{prefix}database.password=... User password (optional if user and password provided in
                                   url; prompted on standard input if user is provided and
                                   password is not)
   -D{prefix}database.flavor=...   What kind of database it is (optional, will guess based
                                   on the url if this is not provided)
   -D{prefix}database.driver=...   The Java class of the JDBC driver to load (optional, will
                                   guess based on the flavor if this is not provided)
 

Parameters:

propertyPrefix - a prefix to attach to each system property - be sure to include the dot if desired (e.g. "mydb." for properties like -Dmydb.database.url)

transact

public void transact(DbCode code)

transactReturning

public <T> T transactReturning(DbCodeTyped<T> code)

transact

public void transact(DbCodeTx code)

get

public Database get()

Specified by:

get in interface Supplier<Database>

fakeBuilder

public DatabaseProvider.Builder fakeBuilder()

commitAndClose

public void commitAndClose()

rollbackAndClose

public void rollbackAndClose()

createPool

public static DatabaseProvider.Pool createPool(Config config)