Review doc on advanced datasource customization

Closes gh-7652

spring-boot-docs/src/main/java/org/springframework/boot/jdbc/BasicDataSourceExample.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.jdbc;
+
+import javax.sql.DataSource;
+
+import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Example configuration for configuring a very basic custom {@link DataSource}.
+ *
+ * @author Stephane Nicoll
+ */
+public class BasicDataSourceExample {
+
+	/**
+	 * A configuration that exposes an empty {@link DataSource}.
+	 */
+	@Configuration
+	static class BasicDataSourceConfiguration {
+
+		// tag::configuration[]
+		@Bean
+		@ConfigurationProperties("app.datasource")
+		public DataSource dataSource() {
+			return DataSourceBuilder.create().build();
+		}
+		// end::configuration[]
+
+	}
+}

spring-boot-docs/src/main/java/org/springframework/boot/jdbc/CompleteTwoDataSourcesExample.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.jdbc;
+
+import javax.sql.DataSource;
+
+import org.springframework.boot.autoconfigure.jdbc.DataSourceProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+/**
+ * Example configuration for configuring two data sources with what Spring Boot does
+ * in auto-configuration.
+ *
+ * @author Stephane Nicoll
+ */
+public class CompleteTwoDataSourcesExample {
+
+	/**
+	 * A complete configuration that exposes two data sources.
+	 */
+	@Configuration
+	static class CompleteDataSourcesConfiguration {
+
+		// tag::configuration[]
+		@Bean
+		@Primary
+		@ConfigurationProperties("app.datasource.foo")
+		public DataSourceProperties fooDataSourceProperties() {
+			return new DataSourceProperties();
+		}
+
+		@Bean
+		@Primary
+		@ConfigurationProperties("app.datasource.foo")
+		public DataSource fooDataSource() {
+			return fooDataSourceProperties()
+					.initializeDataSourceBuilder()
+					.build();
+		}
+
+		@Bean
+		@ConfigurationProperties("app.datasource.bar")
+		public DataSourceProperties barDataSourceProperties() {
+			return new DataSourceProperties();
+		}
+
+
+		@Bean
+		@ConfigurationProperties("app.datasource.bar")
+		public DataSource barDataSource() {
+			return barDataSourceProperties()
+					.initializeDataSourceBuilder()
+					.build();
+		}
+		// end::configuration[]
+
+	}
+
+}

spring-boot-docs/src/main/java/org/springframework/boot/jdbc/ConfigurableDataSourceExample.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.jdbc;
+
+import javax.sql.DataSource;
+
+import com.zaxxer.hikari.HikariDataSource;
+
+import org.springframework.boot.autoconfigure.jdbc.DataSourceProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+/**
+ * Example configuration for configuring a configurable custom {@link DataSource}.
+ *
+ * @author Stephane Nicoll
+ */
+public class ConfigurableDataSourceExample {
+
+	/**
+	 * A configuration that define dedicated settings and reuse
+	 * {@link DataSourceProperties}.
+	 */
+	@Configuration
+	static class ConfigurableDataSourceConfiguration {
+
+		// tag::configuration[]
+		@Bean
+		@Primary
+		@ConfigurationProperties("app.datasource")
+		public DataSourceProperties dataSourceProperties() {
+			return new DataSourceProperties();
+		}
+
+		@Bean
+		@ConfigurationProperties("app.datasource")
+		public HikariDataSource dataSource(DataSourceProperties properties) {
+			return (HikariDataSource) properties.initializeDataSourceBuilder()
+					.type(HikariDataSource.class)
+					.build();
+		}
+		// end::configuration[]
+
+	}
+}

spring-boot-docs/src/main/java/org/springframework/boot/jdbc/SimpleDataSourceExample.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.jdbc;
+
+import javax.sql.DataSource;
+
+import com.zaxxer.hikari.HikariDataSource;
+
+import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Example configuration for configuring a simple {@link DataSource}.
+ *
+ * @author Stephane Nicoll
+ */
+public class SimpleDataSourceExample {
+
+	/**
+	 * A simple configuration that exposes dedicated settings.
+	 */
+	@Configuration
+	static class SimpleDataSourceConfiguration {
+
+		// tag::configuration[]
+		@Bean
+		@ConfigurationProperties("app.datasource")
+		public HikariDataSource dataSource() {
+			return (HikariDataSource) DataSourceBuilder.create()
+					.type(HikariDataSource.class)
+					.build();
+		}
+		// end::configuration[]
+
+	}
+
+}

spring-boot-docs/src/main/java/org/springframework/boot/jdbc/SimpleTwoDataSourcesExample.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.jdbc;
+
+import javax.sql.DataSource;
+
+import org.apache.commons.dbcp2.BasicDataSource;
+
+import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+/**
+ * Example configuration for configuring a configurable secondary {@link DataSource} while
+ * keeping the auto-configuration defaults for the primary one.
+ *
+ * @author Stephane Nicoll
+ */
+public class SimpleTwoDataSourcesExample {
+
+	/**
+	 * A simple configuration that exposes two data sources.
+	 */
+	@Configuration
+	static class SimpleDataSourcesConfiguration {
+
+		// tag::configuration[]
+		@Bean
+		@Primary
+		@ConfigurationProperties("app.datasource.foo")
+		public DataSourceProperties fooDataSourceProperties() {
+			return new DataSourceProperties();
+		}
+
+		@Bean
+		@Primary
+		@ConfigurationProperties("app.datasource.foo")
+		public DataSource fooDataSource() {
+			return fooDataSourceProperties()
+					.initializeDataSourceBuilder()
+					.build();
+		}
+
+
+		@Bean
+		@ConfigurationProperties("app.datasource.bar")
+		public BasicDataSource barDataSource() {
+			return (BasicDataSource) DataSourceBuilder.create()
+					.type(BasicDataSource.class)
+					.build();
+		}
+		// end::configuration[]
+
+	}
+
+}