com.holonplatform.jdbc

## Interface DataSourceBuilder

-     public interface DataSourceBuilder

  Builder to create and configure `DataSource` instances using a `DataSourceConfigProperties` configuration properties source.

  The `DataSource` instances are created and configured using a suitable `DataSourceFactory`, bound to a symbolic type name which can be specified using the `DataSourceConfigProperties.TYPE` property. The `DataSourceFactory` which corresponds to a `DataSource` type name must be registered to build the DataSource using the `registerFactory(DataSourceFactory)` method. Default factories can be registered using default Java `ServiceLoader` extension, through a `com.holonplatform.jdbc.DataSourceFactory` file under the `META-INF/services` folder.

  The builder supports `DataSourcePostProcessor` registration to initialiaze and/or configure the created `DataSource` instances. Default post processors can be registered using default Java `ServiceLoader` extension, through a `com.holonplatform.jdbc.DataSourcePostProcessor` file under the `META-INF/services` folder.

  Since:
    5.0.0
  See Also:
    `DataSourceConfigProperties`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `DataSourceBuilder.Builder` Direct `DataSource` instance builder.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_PRIORITY` Default `DataSourceBuilder` priority if not specified using `Priority` annotation.
    `static String` | `TYPE_BASIC` Default DataSource type: BasicDataSource
    `static String` | `TYPE_DBCP` Default DataSource type: DBCP 2 DataSource
    `static String` | `TYPE_HIKARICP` Default DataSource type: HikariCP DataSource
    `static String` | `TYPE_JNDI` Default DataSource type: JNDI DataSource
    `static String` | `TYPE_TOMCAT` Default DataSource type: Tomcat DataSource

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `DataSource` | `build(DataSourceConfigProperties configurationProperties)` Build a DataSource instance using given configuration properties.
    `static DataSource` | `build(String propertiesFileName)` Convenience method to directly build a `DataSource` using given DataSource configuration properties file name.
    `static DataSource` | `build(String propertiesFileName, ClassLoader classLoader)` Convenience method to directly build a `DataSource` using given DataSource configuration properties file name.
    `static DataSourceBuilder.Builder` | `builder()` Get a `DataSourceBuilder.Builder` to set configuration properties and directly obtain a `DataSource` instance.
    `static DataSourceBuilder` | `create()` Create a new `DataSourceBuilder` using the default ClassLoader.
    `static DataSourceBuilder` | `create(ClassLoader classLoader)` Create a new `DataSourceBuilder`.
    `void` | `registerFactory(DataSourceFactory factory)` Register a `DataSourceFactory` to be used to build `DataSource` instances of the type returned by the `DataSourceFactory.getDataSourceType()` method.
    `void` | `registerPostProcessor(DataSourcePostProcessor postProcessor)` Register a new `DataSourcePostProcessor` to initialiaze and/or configure the created `DataSource` instances.

- - ### Field Detail

    - #### TYPE_BASIC

          static final String TYPE_BASIC

      Default DataSource type: BasicDataSource
      See Also:
        `DataSourceConfigProperties.TYPE`, Constant Field Values

    - #### TYPE_HIKARICP

          static final String TYPE_HIKARICP

      Default DataSource type: HikariCP DataSource
      See Also:
        `DataSourceConfigProperties.TYPE`, Constant Field Values

    - #### TYPE_DBCP

          static final String TYPE_DBCP

      Default DataSource type: DBCP 2 DataSource
      See Also:
        `DataSourceConfigProperties.TYPE`, Constant Field Values

    - #### TYPE_TOMCAT

          static final String TYPE_TOMCAT

      Default DataSource type: Tomcat DataSource
      See Also:
        `DataSourceConfigProperties.TYPE`, Constant Field Values

    - #### TYPE_JNDI

          static final String TYPE_JNDI

      Default DataSource type: JNDI DataSource
      See Also:
        `DataSourceConfigProperties.TYPE`, Constant Field Values

    - #### DEFAULT_PRIORITY

          static final int DEFAULT_PRIORITY

      Default `DataSourceBuilder` priority if not specified using `Priority` annotation.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### registerFactory

          void registerFactory(DataSourceFactory factory)

      Register a `DataSourceFactory` to be used to build `DataSource` instances of the type returned by the `DataSourceFactory.getDataSourceType()` method.

      Any previous binding with given type will be replaced by the given `DataSourceFactory`.

      Parameters:
        `factory` - the factory to register (not null)
      See Also:
        `DataSourceConfigProperties.TYPE`

    - #### registerPostProcessor

          void registerPostProcessor(DataSourcePostProcessor postProcessor)

      Register a new `DataSourcePostProcessor` to initialiaze and/or configure the created `DataSource` instances.
      Parameters:
        `postProcessor` - Post processor to register (not null)

    - #### build

          DataSource build(DataSourceConfigProperties configurationProperties)
                    throws com.holonplatform.core.config.ConfigPropertySet.ConfigurationException

      Build a DataSource instance using given configuration properties.
      Parameters:
        `configurationProperties` - Configuration properties
      Returns:
        DataSource instance configured according to given configuration properties
      Throws:
        `com.holonplatform.core.config.ConfigPropertySet.ConfigurationException` - Error configuring DataSource using given configuration properties

    - #### create

          static DataSourceBuilder create()

      Create a new `DataSourceBuilder` using the default ClassLoader. The builder will be initialized with default `DataSourceFactory`s and `DataSourcePostProcessor`s loaded using default Java `ServiceLoader` extensions.
      Returns:
        A new DataSourceBuilder instance

    - #### create

          static DataSourceBuilder create(ClassLoader classLoader)

      Create a new `DataSourceBuilder`. The builder will be initialized with default `DataSourceFactory`s and `DataSourcePostProcessor`s loaded using default Java `ServiceLoader` extensions.
      Parameters:
        `classLoader` - The ClassLoader to use to initialize the builder (not null)
      Returns:
        A new DataSourceBuilder instance

    - #### build

          static DataSource build(String propertiesFileName)

      Convenience method to directly build a `DataSource` using given DataSource configuration properties file name.

      See `DataSourceConfigProperties` for available DataSource configuration property names and meaning.

      Parameters:
        `propertiesFileName` - DataSource configuration properties file name (not null)
      Returns:
        A new `DataSource` instance built according to provided configuration properties
      Throws:
        `com.holonplatform.core.config.ConfigPropertySet.ConfigurationException` - Error configuring a DataSource using given configuration properties

    - #### build

          static DataSource build(String propertiesFileName,
                                  ClassLoader classLoader)

      Convenience method to directly build a `DataSource` using given DataSource configuration properties file name.

      See `DataSourceConfigProperties` for available DataSource configuration property names and meaning.

      Parameters:
        `propertiesFileName` - DataSource configuration properties file name (not null)
        `classLoader` - The ClassLoader to use to load the file
      Returns:
        A new `DataSource` instance built according to provided configuration properties
      Throws:
        `com.holonplatform.core.config.ConfigPropertySet.ConfigurationException` - Error configuring a DataSource using given configuration properties

    - #### builder

          static DataSourceBuilder.Builder builder()

      Get a `DataSourceBuilder.Builder` to set configuration properties and directly obtain a `DataSource` instance.
      Returns:
        A new `DataSource` builder

Copyright © 2019 The Holon Platform. All rights reserved.