From 7dab75f7891b13fcbb212795b5b788e6311a9e46 Mon Sep 17 00:00:00 2001 From: Ben Klein Date: Tue, 8 Sep 2015 14:27:05 -0500 Subject: [PATCH] document 1.2.1 feature: control over pooling impl. detection priority --- ...spring-cloud-spring-service-connector.adoc | 79 ++++++++++++++++++- 1 file changed, 75 insertions(+), 4 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc b/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc index e912064..00e62f1 100644 --- a/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc +++ b/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc @@ -155,10 +155,7 @@ public RabbitConnectionFactory rabbitFactory() { [NOTE] ==== -Spring Cloud Spring Service Connector selects from a number of connection-pooling `DataSource` implementations based on availability and following a set priority. See <<_detection_and_prioritization_of_code_datasource_code_implementations,Detection and Prioritization of `DataSource` Implementations>>. -//// -If you need to reorder the prioritization of supported implementations, see <<_detection_and_prioritization_of_code_datasource_code_implementations,Detection and Prioritization of `DataSource` Implementations>> below. -//// +Spring Cloud Spring Service Connector selects from a number of connection-pooling `DataSource` implementations based on availability and following a set priority. For details on the priority, see <<_detection_and_prioritization_of_code_datasource_code_implementations,Detection and Prioritization of `DataSource` Implementations>>. If you need to reorder the prioritization of supported implementations, see <<_reordering_implementation_priority,Reordering Implementation Priority>>. ==== To connect to a unique relational database service, you can create a service bean using `dataSource()`. The following example connects to the only relational database service bound to the application. @@ -221,6 +218,41 @@ When creating a `DataSource`, the connector prefers any of the following four co The connector uses the first of these that is found on the classpath. If none of these are on the classpath, the connector falls back to a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/jdbc/datasource/SimpleDriverDataSource.html[`SimpleDriverDataSource`], which does not reuse connections. +====== Reordering Implementation Priority + +[NOTE] +==== +This feature is available only in Spring Cloud Connectors 1.2.1 and later. +==== + +If you would like to reorder the priorities given to supported `DataSource` implementations, you can provide a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/relational/DataSourceConfig.html[`DataSourceConfig`] containing a `List` which uses your own ordering. You can name an implementation either by its full class name or by a string included in its class name. + +The following example connects to the `my-own-personal-sql` MySQL service and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/relational/DataSourceConfig.html[`DataSourceConfig`], which is initialized with a `List` of `DataSource` implementation class names. + +[source,java] +---- +//Set order of DataSource implementations, using a List of full class names +@Bean +public DataSource dataSource() { + List dataSourceNames = Arrays.asList("TomcatJdbcPooledDataSourceCreator", "HikariCpPooledDataSourceCreator", "BasicDbcpPooledDataSourceCreator"); + DataSourceConfig dbConfig = new DataSourceConfig(dataSourceNames); + return connectionFactory().dataSource("my-own-personal-sql", dbConfig); +} +---- + +The following example connects to the `my-own-personal-sql` MySQL service and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/relational/DataSourceConfig.html[`DataSourceConfig`], which is initialized with a `List` of strings contained in `DataSource` implementations’ class names. + +[source,java] +---- +//Set order of DataSource implementations, using a List of strings contained in class names +@Bean +public DataSource dataSource() { + List dataSourceNames = Arrays.asList("TomcatJdbc", "HikariCp", "BasicDbcp"); + DataSourceConfig dbConfig = new DataSourceConfig(dataSourceNames); + return connectionFactory().dataSource("my-own-personal-sql", dbConfig); +} +---- + ==== MongoDB To connect to a unique MongoDB service, you can create a service bean using `mongoDbFactory()`. The following example connects to the only MongoDB service bound to the application. @@ -526,6 +558,11 @@ To set connection properties on a RabbitMQ service, you can use the `>. If you need to reorder the prioritization of supported implementations, see <<_reordering_implementation_priority_2,Reordering Implementation Priority>>. +==== + To connect to a relational database service, you can use the `` element. The following example connects to the only relational database service bound to the application. [source,xml] @@ -570,6 +607,40 @@ To configure pool settings on a relational database service, you can use the ` ---- +===== Detection and Prioritization of `DataSource` Implementations + +When creating a `DataSource`, the connector prefers any of the following four connection-pooling `DataSource` implementations, in the order shown. + +1. https://commons.apache.org/proper/commons-dbcp/[Apache Commons DBCP and DBCP 2] +2. Tomcat DBCP +3. https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html[Tomcat JDBC Connection Pool] +4. http://brettwooldridge.github.io/HikariCP/[HikariCP] + +The connector uses the first of these that is found on the classpath. If none of these are on the classpath, the connector falls back to a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/jdbc/datasource/SimpleDriverDataSource.html[`SimpleDriverDataSource`], which does not reuse connections. + +====== Reordering Implementation Priority + +[NOTE] +==== +This feature is available only in Spring Cloud Connectors 1.2.1 and later. +==== + +If you would like to reorder the priorities given to supported `DataSource` implementations, you can use the `` nested element. For each implementation, include a `` element for a string contained in the class name. List these in the order that you wish to have the connector follow. + +The following example connects to the `my-own-personal-sql` MySQL service and uses the `` element to specify the priority of supported `DataSource` implementations. + +[source,xml] +---- + + + + TomcatJdbc + TomcatDbcp + BasicDbcp + + +---- + ==== MongoDB To connect to a MongoDB service, you can use the `` element. The following example connects to the only MongoDB service bound to the application.