com.holonplatform.jdbc.spring

## Annotation Type EnableDataSource

-     @Target(value=TYPE)
       @Retention(value=RUNTIME)
       @Documented
       @Inherited
       @Import(value=DataSourceRegistrar.class)
      public @interface EnableDataSource

  Annotation to be used on Spring Configuration classes to setup a `DataSource` using external configuration properties according to `DataSourceConfigProperties` property names.

  The actual `DataSource` implementation to be used can be specified using a symbolic type name, specified through the `DataSourceConfigProperties.TYPE` configuration property. By default, the following types are supported:

  - `com.holonplatform.jdbc.BasicDataSource`: Create `BasicDataSource` instances, to be used typically for testing purposes. It is a simple DataSource implementation, using the `DriverManager` class and returning a new `Connection` from every `getConnection` call.
  - `com.zaxxer.hikari.HikariDataSource`: Create HikariCP connection pooling DataSource instances. The HikariCP library dependency must be available in classpath. All default configuration properties are supported, and additional Hikari-specific configuration properties can be specified using the `hikari` prefix before the actual property name, for example: `holon.datasource.hikari.connectionTimeout=50000`
  - `org.apache.commons.dbcp2.BasicDataSource`: Create DBCP2 connection pooling DataSource instances. The Apache Commons DBCP 2 library dependency must be available in classpath. All default configuration properties are supported, and additional DBCP-specific configuration properties can be specified using the `dbcp` prefix before the actual property name, for example: `holon.datasource.dbcp.maxWaitMillis=3000`
  - `org.apache.tomcat.jdbc.pool.DataSource`: Create Tomcat JDBC connection pooling DataSource instances. The tomcat-jdbc library dependency must be available in classpath. All default configuration properties are supported, and additional Tomcat-specific configuration properties can be specified using the `tomcat` prefix before the actual property name, for example: `holon.datasource.tomcat.maxAge=5000`
  - `JNDI`: Obtain a DataSource using JNDI. The `jndi-name` configuration property is required to specify the JNDI name to which the DataSource is bound in the JNDI context.

  When the `DataSourceConfigProperties.TYPE` configuration property is not specified, the default DataSource type selection strategy is defined as follows:

  1. If the HikariCP dependecy is present in classpath, the `com.zaxxer.hikari.HikariDataSource` type will be used;
  2. If the Apache Commons DBCP2 dependecy is present in classpath, the `org.apache.commons.dbcp2.BasicDataSource` type will be used;
  3. If the Tomcat JDBC dependecy is present in classpath, the `org.apache.tomcat.jdbc.pool.DataSource` type will be used;
  4. Otherwise, the `com.holonplatform.jdbc.BasicDataSource` type is used as fallback

  A data context id can be specified using `dataContextId()`, to discriminate configuration properties using given id as property prefix, and setting data context id as Spring bean qualifier to allow bean injection when multiple `DataSource` bean instances are registered in context, for example using `Qualifier` annotation.

  When a data context id is specified, configuration properties must be written using that id as prefix, for example, if data context id is `myid`:
  `holon.datasource.myid.url=...`

  The DataSource bean is registered using `DEFAULT_DATASOURCE_BEAN_NAME` as bean name if no data context id is specified. Otherwise, bean name is composed using `DEFAULT_DATASOURCE_BEAN_NAME`, an underscore character and the data context id String, for example: `dataSource_mydatacontextid`.

  In case of multiple DataSources, `primary()` or the external property `SpringDataSourceConfigProperties.PRIMARY` can be used to mark one of the DataSources as primary candidate for dependency injection when a qualifier is not specified.

  Since:
    5.0.0

- - ### Field Summary

    Fields
    Modifier and Type | Fields and Description
    --- | ---
    `static String` | `DEFAULT_DATASOURCE_BEAN_NAME` Default `DataSource` registration bean name.
    `static String` | `DEFAULT_TRANSACTIONMANAGER_BEAN_NAME` Default `PlatformTransactionManager` registration bean name.

  - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `dataContextId` Bind DataSource to given data context id.
    `boolean` | `enableTransactionManager` Whether to register a JDBC `PlatformTransactionManager` to enable transactions management using Spring's transaction infrastructure, for example to enable `Transactional` annotations.
    `com.holonplatform.spring.PrimaryMode` | `primary` Whether to qualify `DataSource` bean as `primary`, i.e. the preferential bean to be injected in a single-valued dependency when multiple candidates are present.

- - ### Field Detail

    - #### DEFAULT_DATASOURCE_BEAN_NAME

          public static final String DEFAULT_DATASOURCE_BEAN_NAME

      Default `DataSource` registration bean name.

  - - #### DEFAULT_TRANSACTIONMANAGER_BEAN_NAME

          public static final String DEFAULT_TRANSACTIONMANAGER_BEAN_NAME

      Default `PlatformTransactionManager` registration bean name.

  - ### Element Detail

    - #### dataContextId

          public abstract String dataContextId

      Bind DataSource to given data context id.

      The data context id will be used as DataSource bean qualifier, allowing DataSources bean discrimination in case of multiple data context ids. You must ensure different data context ids are used when configuring multiple data sources using this annotation.

      Returns:
        Data context id
      Default:
        ""

  - - #### primary

          public abstract com.holonplatform.spring.PrimaryMode primary

      Whether to qualify `DataSource` bean as `primary`, i.e. the preferential bean to be injected in a single-valued dependency when multiple candidates are present.

      When mode is `PrimaryMode.AUTO`, the registred DataSource bean is marked as primary or not according to the `SpringDataSourceConfigProperties.PRIMARY` configuration property, if present. If the property is not specified, the bean is not registered as primary by default.

      Returns:
        Primary mode, defaults to `PrimaryMode.AUTO`
      Default:
        com.holonplatform.spring.PrimaryMode.AUTO

  - - #### enableTransactionManager

          public abstract boolean enableTransactionManager

      Whether to register a JDBC `PlatformTransactionManager` to enable transactions management using Spring's transaction infrastructure, for example to enable `Transactional` annotations.

      Default is `false`.

      Returns:
        `true` to register a `PlatformTransactionManager`, `false` otherwise.
      Default:
        false

Copyright © 2019 The Holon Platform. All rights reserved.