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 8de0fa2..880489b 100644 --- a/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc +++ b/docs/src/main/asciidoc/spring-cloud-spring-service-connector.adoc @@ -9,7 +9,7 @@ The Spring Service Connector is part of the <> project. -This library provides `ServiceConnectorCreator` implementations for `javax.sql.DataSource` and various link:http://projects.spring.io/spring-data/[Spring Data] connector factories. It also provides Java configuration and XML namespace support for connecting to cloud services, accessing cloud services, and accessing application properties. +This library provides `ServiceConnectorCreator` implementations for `javax.sql.DataSource` and various http://projects.spring.io/spring-data/[Spring Data] connector factories. It also provides Java configuration and XML namespace support for connecting to cloud services, accessing cloud services, and accessing application properties. == The Java Configuration @@ -17,14 +17,40 @@ Typical use of the Java configuration involves extending the `AbstractCloudConfi [TIP] ==== -If you are migrating an application that uses link:https://spring.io/blog/2011/11/04/using-cloud-foundry-services-with-spring-part-2-auto-reconfiguration/[auto-reconfiguration], you might first try the <<_scanning_for_services,service-scanning approach>> until you need more explicit control. +If you are migrating an application that uses https://spring.io/blog/2011/11/04/using-cloud-foundry-services-with-spring-part-2-auto-reconfiguration/[auto-reconfiguration], you might first try the <<_scanning_for_services,service-scanning approach>> until you need more explicit control. ==== -The Spring Service Connector Java configuration also offers a way to expose application and service properties in case you want lower-level access when creating your own service connectors (or for debugging purposes, etc.). +The Spring Service Connector Java configuration also offers a way to expose application and service properties in case you want lower-level access when creating your own service connectors (or for debugging purposes, etc.). === Creating Service Beans -The configuration shown in the following example creates a `DataSource` bean that connects to the only relational database service bound to the application (it will fail if there is no such unique service). It also creates a `MongoDbFactory` bean, which again connects to the only MongoDB service bound to the application. (For ways to connect to other services, see the link:http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/config/java/AbstractCloudConfig.html[Javadoc for `AbstractCloudConfig`].) +If you do not wish to extend `AbstractCloudConfig`, you can create your own http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/Cloud.html[`Cloud`] object as an alternative. + +[source,java] +---- +@Bean +public Cloud cloud() { + return new CloudFactory().getCloud(); +} +---- + +The following example creates a `DataSource` bean (without configuration) using the http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/Cloud.html#getSingletonServiceConnector(java.lang.Class,%20org.springframework.cloud.service.ServiceConnectorConfig)[`getSingletonServiceConnector()`] method on `Cloud`. + +[source,java] +---- +@Bean +@ConfigurationProperties(DataSourceProperties.PREFIX) +public DataSource dataSource() { + return cloud().getSingletonServiceConnector(DataSource.class, null); +} +---- + +[NOTE] +==== +Following examples presume a configuration class which extends `AbstractCloudConfig`. +==== + +The configuration shown in the following example creates a `DataSource` bean that connects to the only relational database service bound to the application (it will fail if there is no such unique service). It also creates a `MongoDbFactory` bean, which again connects to the only MongoDB service bound to the application. (For ways to connect to other services, see the http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/config/java/AbstractCloudConfig.ServiceConnectionFactory.html[Javadoc for `AbstractCloudConfig.ServiceConnectionFactory`].) [source,java] ---- @@ -33,12 +59,12 @@ class CloudConfig extends AbstractCloudConfig { public DataSource inventoryDataSource() { return connectionFactory().dataSource(); } - + @Bean public MongoDbFactory documentMongoDbFactory() { return connectionFactory().mongoDbFactory(); } - + // (More beans to obtain service connectors) } ---- @@ -51,9 +77,9 @@ You can specify a bean name by providing a value in the `@Bean` annotation. ---- Otherwise, bean names will match the method names. (This works in the same way as does Spring's Java configuration.) - + If you have more than one service of a type bound to the application or want explicit control over the services to which a bean is bound, you can pass the service names to methods such as `dataSource()` and `mongoDbFactory()`. - + [source,java] ---- class CloudConfig extends AbstractCloudConfig { @@ -70,12 +96,12 @@ class CloudConfig extends AbstractCloudConfig { // (More beans to obtain service connectors) } ---- - -Out of the box, the Spring Service Connector provides methods for connecting to a variety of services. For information on creating connections to supported services, see below. + +Out of the box, the Spring Service Connector provides methods for connecting to a variety of services. For information on using the Java configuration to create connections to supported services, see below. ==== RabbitMQ -To connect to a unique RabbitMQ service, create a service bean using `rabbitConnectionFactory()`. The following example connects to the only RabbitMQ service bound to the application. +To connect to a unique RabbitMQ service, you can create a service bean using `rabbitConnectionFactory()`. The following example connects to the only RabbitMQ service bound to the application. [source,java] ---- @@ -127,7 +153,7 @@ public RabbitConnectionFactory rabbitFactory() { ==== Relational database (DB2, MySQL, Oracle, PostgreSQL, SQL Server) -To connect to a unique relational database service, create a service bean using `dataSource()`. The following example connects to the only relational database service bound to the application. +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. [source,java] ---- @@ -178,23 +204,142 @@ public DataSource dataSource() { ==== MongoDB -Coming soon... +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. -==== Application monitoring (New Relic) +[source,java] +---- +//Connect to the only available MongoDB service +@Bean +public MongoDbFactory mongoFactory() { + return connectionFactory().mongoDbFactory(); +} +---- -Coming soon... +To provide configuration for a unique MongoDB service, you can use an overloaded `mongoDbFactory()` variant. The following example connects to the only MongoDB service bound to the application and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/document/MongoDbFactoryConfig.html[`MongoDbFactoryConfig`] that sets `writeConcern` to `NONE`, `connectionsPerHost` to 50, and `maxWaitTime` to 200. + +[source,java] +---- +//Connect to the only available MongoDB service, supplying configuration +@Bean +public MongoDbFactory mongoFactory() { + MongoDbFactoryConfig mongoConfig = new MongoDbFactoryConfig("NONE", 50, 200); + return connectionFactory().mongoDbFactory(mongoConfig); +} +---- + +To connect to a specific MongoDB service, you can use an overloaded variant of `mongoDbFactory()`. The following example connects specifically to the `mongo-service` MongoDB service. + +[source,java] +---- +//Connect to the 'mongo-service' MongoDB service +@Bean +public MongoDbFactory mongoFactory() { + return connectionFactory().mongoDbFactory("mongo-service"); +} +---- + +To connect to a specific MongoDB service and provide configuration, you can use an overloaded `mongoDbFactory()` variant. The following example connects to the `mongo-service` MongoDB service and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/document/MongoDbFactoryConfig.html[`MongoDbFactoryConfig`] that sets `writeConcern` to `NONE`, `connectionsPerHost` to 50, and `maxWaitTime` to 200. + +[source,java] +---- +//Connect to the only available MongoDB service, supplying configuration +@Bean +public MongoDbFactory mongoFactory() { + MongoDbFactoryConfig mongoConfig = new MongoDbFactoryConfig("NONE", 50, 200); + return connectionFactory().mongoDbFactory("mongo-service", mongoConfig); +} +---- ==== Redis -Coming soon... +To connect to a unique Redis service, you can create a service bean using `redisConnectionFactory()`. The following example connects to the only Redis service bound to the application. -==== SMTP +[source,java] +---- +//Connect to the only available Redis service +@Bean +public RedisConnectionFactory redisFactory() { + return connectionFactory().redisConnectionFactory(); +} +---- -Coming soon... +To provide configuration for a unique Redis service, you can use an overloaded `redisConnectionFactory()` variant. The following example connects to the only Redis service bound to the application and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/PooledServiceConnectorConfig.html[`PooledServiceConnectorConfig`], which is initialized with a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/PooledServiceConnectorConfig.PoolConfig.html[`PoolConfig`] that sets a `minPoolSize` of 5, a `maxPoolSize` of 30, and a `maxWaitTime` of 3000. + +[source,java] +---- +//Connect to the only available Redis service, supplying configuration +@Bean +public RedisConnectionFactory redisFactory() { + PoolConfig poolConfig = new PoolConfig(5, 30, 3000); + PooledServiceConnectorConfig redisConfig = new PooledServiceConnectorConfig(poolConfig); + return connectionFactory().redisConnectionFactory(redisConfig); +} +---- + +To connect to a specific Redis service, you can use an overloaded variant of `redisConnectionFactory()`. The following example connects specifically to the `redis-service` Redis service. + +[source,java] +---- +//Connect to the 'redis-service' Redis service +@Bean +public RedisConnectionFactory redisFactory() { + return connectionFactory().redisConnectionFactory("redis-service"); +} +---- + +To connect to a specific Redis service and provide configuration, you can use an overloaded `redisConnectionFactory()` variant. The following example connects to the `redis-service` Redis service and supplies configuration using a http://docs.spring.io/autorepo/docs/spring-cloud/1.1.2.BUILD-SNAPSHOT/api/org/springframework/cloud/service/keyval/RedisConnectionFactoryConfig.html[`RedisConnectionFactoryConfig`], which is initialized with a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/PooledServiceConnectorConfig.PoolConfig.html[`PoolConfig`] that sets `writeConcern` to `NONE`, `connectionsPerHost` to 50, and `maxWaitTime` to 200. + +[source,java] +---- +//Connect to the 'redis-service' Redis service, supplying configuration +@Bean +public RedisConnectionFactory redisFactory() { + PoolConfig poolConfig = new PoolConfig(5, 30, 3000); + PooledServiceConnectorConfig redisConfig = new RedisConnectionFactoryConfig(poolConfig); + return connectionFactory().redisConnectionFactory("redis-service", redisConfig); +} +---- + +To connect to a specific Redis service and set properties on the service, you can use an overloaded variant of `redisConnectionFactory()`. The following example connects to the `redis-service` Redis service and sets the `timeout` property using a http://docs.spring.io/autorepo/docs/spring-cloud/1.1.2.BUILD-SNAPSHOT/api/org/springframework/cloud/service/keyval/RedisConnectionFactoryConfig.html[`RedisConnectionFactoryConfig`] initialized with a `HashMap` that contains the property key and value. + +[source,java] +---- +//Connect to the 'redis-service' Redis service, setting a property +@Bean +public RedisConnectionFactory redisFactory() { + Map properties = new HashMap(); + properties.put("timeout", 10); + RedisConnectionFactoryConfig redisConfig = new RedisConnectionFactoryConfig(properties); + return connectionFactory().redisConnectionFactory("redis-service", redisConfig); +} +---- + +To connect to a specific Redis service and provide configuration and property values for the service, you can use an overloaded variant of `redisConnectionFactory()`. The following example connects to the `redis-service` Redis service and uses a http://docs.spring.io/autorepo/docs/spring-cloud/1.1.2.BUILD-SNAPSHOT/api/org/springframework/cloud/service/keyval/RedisConnectionFactoryConfig.html[`RedisConnectionFactoryConfig`] initialized with a http://docs.spring.io/autorepo/docs/spring-cloud/current/api/org/springframework/cloud/service/PooledServiceConnectorConfig.PoolConfig.html[`PoolConfig`] (which sets `writeConcern` to `NONE`, `connectionsPerHost` to 50, and `maxWaitTime` to 200) and a `HashMap` (which contains a property key and value) to configure the service and set its `timeout` property. + +[source,java] +---- +//Connect to the 'redis-service' Redis service, providing configuration and setting a property +@Bean +public RedisConnectionFactory redisFactory() { + Map properties = new HashMap(); + properties.put("timeout", 10); + PoolConfig poolConfig = new PoolConfig(5, 30, 3000); + RedisConnectionFactoryConfig redisConfig = new RedisConnectionFactoryConfig(poolConfig, properties); + return connectionFactory().redisConnectionFactory("redis-service", redisConfig); +} +---- === Connecting to Generic Services -The Java configuration supports access to generic services (services which don't have a directly mapped method; this is typical for a newly-introduced service or when connecting to a private service in a private PaaS) through the `service()` method. It follows the same pattern as `dataSource()` etc., except that it allows you to supply the connector type as an additional parameter. +The Java configuration supports access to generic services (services which don't have a directly mapped method; this is typical for a newly-introduced service or when connecting to a private service in a private PaaS) through the `service()` method. It follows the same pattern as `dataSource()` etc., except that it allows you to supply the connector type as an additional parameter. The following example connects to a hypothetical service of type `Search`, called `search-service`. + +[source,java] +---- +@Bean +public Search search() { + return connectionFactory().service("search-service", Search.class); +} +---- === Scanning for Services @@ -207,7 +352,7 @@ You can scan for each bound service using the `@ServiceScan` annotation. (This i class CloudConfig { } ---- - + In the above example, the configuration will create one bean of the appropriate type (such as a `DataSource` in the case of a relational database service). Each bean will have an `id` matching the corresponding service name. You can inject such beans using autowiring. @@ -284,6 +429,188 @@ Other namespace elements which create service connectors include: ---- +For information on using the `` namespace to create connections to services with built-in support in the Spring Service Connector, see below. + +==== RabbitMQ + +To connect to a RabbitMQ service, you can use the `` element. The following example connects to the only RabbitMQ service bound to the application. + +[source,xml] +---- + + +---- + +To connect to a specific RabbitMQ service, you can use the `service-name` attribute. The following example connects specifically to the `bunnymq` RabbitMQ service. + +[source,xml] +---- + + +---- + +To specify an id for the RabbitMQ connection bean, you can use the `id` attribute. The following example connects specifically to the `bunnymq` RabbitMQ service with a bean given the id `rabbitmq`. + +[source,xml] +---- + + +---- + +To set properties on a RabbitMQ service, you can use the `` nested element. The following example connects specifically to the `bunnymq` RabbitMQ service with a bean given the id `rabbitmq` and uses the `` element to set the size of the channel cache to 200. + +[source,xml] +---- + + + + +---- + +To set connection properties on a RabbitMQ service, you can use the `` nested element. The following example connects specifically to the `bunnymq` RabbitMQ service with a bean given the id `rabbitmq`. It uses the `` element to set the size of the channel cache to 200, and it uses the `` element to set a heartbeat timeout of 5 seconds and a connection timeout of 10 milliseconds. + +[source,xml] +---- + + + + + + + + +---- + +==== Relational database (DB2, MySQL, Oracle, PostgreSQL, SQL Server) + +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] +---- + + +---- + +To connect to a specific relational database service, you can use the `service-name` attribute. The following example connects specifically to the `my-own-personal-sql` MySQL service. + +[source,xml] +---- + + +---- + +To specify an id for the relational database connection bean, you can use the `id` attribute. The following example connects specifically to the `my-own-personal-sql` MySQL service with a bean given the id `mysql`. + +[source,xml] +---- + + +---- + +To set connection properties on a relational database service, you can use the `` nested element. The following example connects specifically to the `my-own-personal-sql` MySQL service with a bean given the id `mysql` and uses the `` element to set the `useUnicode` and `characterEncoding` properties. + +[source,xml] +---- + + + + +---- + +To configure pool settings on a relational database service, you can use the `` nested element. The following example connects specifically to the `my-own-personal-sql` MySQL service with a bean given the id `mysql`. It uses the `` element to set a `pool-size` of 5–30 and a `max-wait-time` of 3000 milliseconds. + +[source,xml] +---- + + + + +---- + +==== 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. + +[source,xml] +---- + + +---- + +To connect to a specific MongoDB service, you can use the `service-name` attribute. The following example connects specifically to the `mongo-service` MongoDB service. + +[source,xml] +---- + + +---- + +To specify an id for the MongoDB connection bean, you can use the `id` attribute. The following example connects specifically to the `mongo-service` MongoDB service with a bean given the id `mongo`. + +[source,xml] +---- + + +---- + +To set properties on a MongoDB service, you can use the `` nested element. The following example connects specifically to the `mongo-service` MongoDB service with a bean given the id `mongo` and uses the `` element to allow 50 connections per host. + +[source,xml] +---- + + + + +---- + +==== Redis + +To connect to a Redis service, you can use the `` element. The following example connects to the only Redis service bound to the application. + +[source,xml] +---- + + +---- + +To connect to a specific Redis service, you can use the `service-name` attribute. The following example connects specifically to the `redis-service` Redis service. + +[source,xml] +---- + + +---- + +To specify an id for the Redis connection bean, you can use the `id` attribute. The following example connects specifically to the `redis-service` Redis service with a bean given the id `redis`. + +[source,xml] +---- + + +---- + +To set connection properties on a Redis service, you can use the `` nested element. The following example connects specifically to the `redis-service` Redis service with a bean given the id `redis` and uses the `` element to set a `timeout` of `10`. + +[source,xml] +---- + + + + + + +---- + +To configure pool settings on a Redis service, you can use the `` nested element. The following example connects specifically to the `redis-service` Redis service with a bean given the id `redis`. It uses the `` element to set a `pool-size` of 5–30 and a `max-wait-time` of 3000 milliseconds. + +[source,xml] +---- + + + + +---- + === Connecting to Generic Services Spring Service Connector also supports a generic `` namespace for connecting to a service with no directly-mapped element (this is typical for a newly-introduced service or when connecting to a private service in a private PaaS). You must specify either the `connector-type` attribute (for locating a unique service by type) or the `service-name` attribute. @@ -299,5 +626,9 @@ Besides these elements (which create only one bean per element), Spring Service === Accessing Service Properties -Lastly, Spring Service Connector provides a `` element, which exposes properties for the application and for services. +Spring Service Connector also provides a `` element, which exposes properties for the application and for services. +[source,xml] +---- + +----