Ben Klein
@@ -1,33 +0,0 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
|
||||
= Spring Cloud Cloud Foundry Connector
|
||||
|
||||
[[spring-cloud-connectors-install]]
|
||||
|
||||
|
||||
This connector will discover services bound to an application running in Cloud Foundry. It currently knows about:
|
||||
|
||||
* PostgreSQL
|
||||
* MySQL
|
||||
* Oracle
|
||||
* Redis
|
||||
* MongoDB
|
||||
* RabbitMQ
|
||||
* SMTP gateway
|
||||
* application monitoring (New Relic)
|
||||
|
||||
Since Cloud Foundry enumerates each service in a consistent format, Spring Cloud does not care which service provider is providing it.
|
||||
|
||||
== Supporting new service types
|
||||
|
||||
Extend `CloudFoundryServiceInfoCreator` with a creator for <<spring-cloud-core.adoc#_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to
|
||||
|
||||
----
|
||||
META-INF/service/org.springframework.cloud.cloudfoundry.CloudFoundryServiceInfoCreator
|
||||
----
|
||||
@@ -1,45 +0,0 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
|
||||
= Spring Cloud Heroku Connector
|
||||
|
||||
[[spring-cloud-connectors-install]]
|
||||
|
||||
This connector will discover services bound to an application running in Heroku. It currently knows about:
|
||||
|
||||
* PostgreSQL (Heroku)
|
||||
* MySQL (ClearDB)
|
||||
* Redis (RedisToGo, Redis Cloud, RedisGreen, openredis)
|
||||
* MongoDB (MongoLab, MongoHQ, MongoSoup)
|
||||
* RabbitMQ (CloudAMQP)
|
||||
|
||||
Pull requests for adding additional services are welcome.
|
||||
|
||||
== Supporting additional providers for existing service types
|
||||
|
||||
To add support for discovering a new provider for a service already listed above, add the provider's environment prefix to the list in `getEnvPrefixes()` on the `ServiceInfoCreator` class.
|
||||
|
||||
== Supporting new service types
|
||||
|
||||
Extend `HerokuServiceInfoCreator` with a creator for <<spring-cloud-core.adoc#_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to
|
||||
|
||||
----
|
||||
META-INF/service/org.springframework.cloud.heroku.HerokuServiceInfoCreator
|
||||
----
|
||||
|
||||
== Limitations
|
||||
|
||||
Unlike CloudFoundry, Heroku exposes very little information about the app that is retrievable from within a running instance. For example, there is no good way to find the name of the application. Therefore, if an app desires such info, it needs to make it available through environment variables.
|
||||
|
||||
To have sensible app name available through `ApplicationInstanceInfo`, set the `SPRING_CLOUD_APP_NAME` environment variable
|
||||
|
||||
----
|
||||
heroku config:add SPRING_CLOUD_APP_NAME=myappname --app myappname
|
||||
----
|
||||
|
||||
If this env variable is not set, the app name will be set to `<unknown>`.
|
||||
@@ -1,79 +0,0 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
|
||||
= Spring Cloud local-configuration Connector
|
||||
|
||||
[[spring-cloud-connectors-install]]
|
||||
|
||||
This connector provides the ability to configure Spring Cloud services locally for development or testing. The current implementation reads from Java properties only. Pull requests for also inspecting environment variables are welcome.
|
||||
|
||||
== Quick start
|
||||
|
||||
Since service URIs contain passwords and should not be stored in code, this connector does not attempt to read service definitions out of the classpath. You can provide service definitions as system properties
|
||||
|
||||
----
|
||||
java -Dspring.cloud.database='mysql://user:pass@host:1234/dbname' -jar my-app.jar
|
||||
----
|
||||
|
||||
and from a configuration properties file either by setting the `spring.cloud.propertiesFile` system property
|
||||
|
||||
----
|
||||
java -Dspring.cloud.propertiesFile=/path/to/spring-cloud.properties -jar my-app.jar
|
||||
----
|
||||
|
||||
or by providing a *bootstrap* properties file on the runtime classpath named `spring-cloud-bootstrap.properties`. This file will be inspected for only the property named `spring.cloud.propertiesFile`, and its value will be interpolated from the system properties.
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.propertiesFile: ${user.home}/.config/myApp/spring-cloud.properties
|
||||
----
|
||||
|
||||
The system properties or the configuration properties file should contain an application ID and the desired services in this format:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.appId: myApp
|
||||
; spring.cloud.{id}: URI
|
||||
spring.cloud.database: mysql://user:pass@host:1234/dbname
|
||||
----
|
||||
|
||||
Service type is determined by the URI scheme. The connector will activate if it finds a property (in the system properties or the configuration properties file) named `spring.cloud.appId`.
|
||||
|
||||
== Property sources
|
||||
|
||||
This connector first attempts to read the system properties generally and a system property named `spring.cloud.propertiesFile` specifically. If the system properties are not readable (the security manager denies `checkPropertiesAccess`), then they will be treated as empty. If a system property named `spring.cloud.propertiesFile` is found, that file will be loaded as a property list.
|
||||
|
||||
=== Providing a bootstrap properties file
|
||||
|
||||
To avoid having to manually configure run configurations or test runners with the path to the configuration properties file, the connector supports reading a templated filename out of the runtime classpath. This file must be named `spring-cloud-bootstrap.properties` and located at the classpath root, and for security the connector will not attempt to read any service URIs out of it. If the connector does find the file, it will read the property `spring.cloud.propertiesFile` and link:http://commons.apache.org/proper/commons-lang/javadocs/api-release/index.html?org/apache/commons/lang3/text/StrSubstitutor.html[substitute the pattern `${system.property}`] with the appropriate value from the system properties. The most useful option is generally `${user.home}`.
|
||||
|
||||
A configuration properties file specified in the system properties will override any bootstrap file that may be available on the classpath.
|
||||
|
||||
=== Property precedence
|
||||
To provide the maximum configuration flexibility, the connector will override any properties (both application ID and service definitions) specified in the file at `spring.cloud.propertiesFile` with system properties defined at runtime. The connector will log a message at `WARN` if you override a service ID.
|
||||
|
||||
== Activating the connector
|
||||
|
||||
The Spring Cloud core expects exactly one cloud connector match the runtime environment. This connector identifies the "local cloud" by the presence of a property named `spring.cloud.appId` in a configuration properties file or the system properties, which will be used in the `ApplicationInstanceInfo`.
|
||||
|
||||
== Service definitions
|
||||
|
||||
If the connector is activated, it will iterate through all the available properties for keys matching the pattern `spring.cloud.{serviceId}`. Each value is interpreted as a URI to the services, and the type of service is determined from the scheme. All of the standard `UriBasedServiceInfo`s are supported.
|
||||
|
||||
== Supporting additional services
|
||||
|
||||
Extend `LocalConfigServiceInfoCreator` with a creator for <<spring-cloud-core.adoc#_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to
|
||||
|
||||
----
|
||||
META-INF/service/org.springframework.cloud.localconfig.LocalConfigServiceInfoCreator
|
||||
----
|
||||
|
||||
|
||||
== Instance ID
|
||||
|
||||
This connector will create a UUID for use as the instance ID, as Java does not provide any portable mechanism for reliably determining hostnames or PIDs.
|
||||
164
docs/src/main/asciidoc/spring-cloud-cloud-foundry-connector.adoc
Normal file
164
docs/src/main/asciidoc/spring-cloud-cloud-foundry-connector.adoc
Normal file
@@ -0,0 +1,164 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
:toclevels: 3
|
||||
|
||||
= Spring Cloud Cloud Foundry Connector
|
||||
|
||||
The Cloud Foundry Connector is part of the <<spring-cloud-connectors.adoc#,Spring Cloud Connectors>> project.
|
||||
|
||||
This connector discovers services that are bound to an application running in Cloud Foundry. (Since Cloud Foundry enumerates each service in a consistent format, Spring Cloud does not care which service provider is providing it.)
|
||||
|
||||
== Cloud Detection
|
||||
|
||||
This connector checks for the presence of a `VCAP_APPLICATION` environment variable. This is a system-provided environment variable which is specific to Cloud Foundry. If the variable exists, the connector will be activated.
|
||||
|
||||
== Service Detection
|
||||
|
||||
The connector inspects Cloud Foundry’s `VCAP_SERVICES` environment variable to detect available services. This variable stores connection and identification information for service instances that are bound to Cloud Foundry applications.
|
||||
|
||||
Below is an example of a `VCAP_SERVICES` entry (edited for brevity).
|
||||
|
||||
[source,json]
|
||||
----
|
||||
"p-rabbitmq": [
|
||||
{
|
||||
"credentials": {
|
||||
"http_api_uri": "http://ca30db57-a396:ddrnu58423q@12.34.567.89:12345/api",
|
||||
"http_api_uris": [
|
||||
"http://ca30db57-a396:ddrnu58423q@12.34.567.89:12345/api"
|
||||
],
|
||||
"uri": "amqp://ca30db57-a396:ddrnu58423q@12.34.567.89/322e7782-eb1f",
|
||||
"uris": [
|
||||
"amqp://ca30db57-a396:ddrnu58423q@12.34.567.89/322e7782-eb1f"
|
||||
]
|
||||
},
|
||||
"label": "p-rabbitmq",
|
||||
"name": "rabbit-bus",
|
||||
"plan": "standard",
|
||||
"tags": [
|
||||
"rabbitmq"
|
||||
]
|
||||
}
|
||||
]
|
||||
----
|
||||
|
||||
For each service, the connector will consider the following fields:
|
||||
|
||||
[cols="3,7", width="100%"]
|
||||
|================================================================================================================================================================================
|
||||
|`tags` |Attributes or names of backing technologies behind the service.
|
||||
|`label` |The service offering’s name (not to be confused with a service _instance’s_ name).
|
||||
|`credentials.uri` |A URI pertaining to the service instance.
|
||||
|`credentials.uris` |URIs pertaining to the service instance.
|
||||
|================================================================================================================================================================================
|
||||
|
||||
If they are present, it will also consider the following fields:
|
||||
|
||||
[cols="3,7", width="100%"]
|
||||
|================================================================================================================================================================================
|
||||
|`credentials.jdbcUrl` |A JDBC connection string.
|
||||
|`credentials.${SCHEME}${URL}` |A service URL, where `${SCHEME}` is a URI scheme used by the service and `${URL}` is one of `Url`, `url`, `Uri`, and `uri`.
|
||||
|================================================================================================================================================================================
|
||||
|
||||
=== Supported Services
|
||||
|
||||
This connector comes with built-in support for a variety of service types and providers. The criteria by which it establishes availability of each service are described below.
|
||||
|
||||
==== Application monitoring (New Relic)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `monitoring` or `newrelic`
|
||||
* `label` beginning with the `monitoring` or `newrelic` tags
|
||||
|
||||
==== DB2
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `sqldb`, `dashDB`, or `db2`
|
||||
* `label` beginning with the `sqldb`, `dashDB`, or `db2` tags
|
||||
* `uri` or `uris` using the scheme `db2`
|
||||
* `jdbcUrl` field in `credentials` using the scheme `db2`
|
||||
* `db2Uri`, `db2uri`, `db2Url`, or `db2url` fields in `credentials`
|
||||
|
||||
==== MongoDB
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `mongodb`
|
||||
* `label` beginning with the `mongodb` tag
|
||||
* `uri` or `uris` using the scheme `mongodb`
|
||||
* `mongodbUri`, `mongodburi`, `mongodbUrl`, or `mongodburl` fields in `credentials`
|
||||
|
||||
==== MySQL
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `mysql`
|
||||
* `label` beginning with the `mysql` tag
|
||||
* `uri` or `uris` using the scheme `mysql`
|
||||
* `jdbcUrl` field in `credentials` using the scheme `mysql`
|
||||
* `mysqlUri`, `mysqluri`, `mysqlUrl`, or `mysqlurl` fields in `credentials`
|
||||
|
||||
==== Oracle
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `uri` or `uris` using the scheme `oracle`
|
||||
* `jdbcUrl` field in `credentials` using the scheme `oracle`
|
||||
* `oracleUri`, `oracleuri`, `oracleUrl`, or `oracleurl` fields in `credentials`
|
||||
|
||||
==== PostgreSQL
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `postgresql`
|
||||
* `label` beginning with the `postgresql` tag
|
||||
* `uri` or `uris` using the scheme `postgres`
|
||||
* `jdbcUrl` field in `credentials` using the scheme `postgres`
|
||||
* `postgresUri`, `postgresuri`, `postgresUrl`, or `postgresurl` fields in `credentials`
|
||||
|
||||
==== RabbitMQ
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `rabbitmq`
|
||||
* `label` beginning with the `rabbitmq` tag
|
||||
* `uri` or `uris` using the scheme `amqp` or `amqps`
|
||||
* `amqpUri`, `amqpuri`, `amqpsUri`, `amqpsuri`, `amqpUrl`, `amqpurl`, `amqpsUrl`, or `amqpsurl` fields in `credentials`
|
||||
|
||||
==== Redis
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `redis`
|
||||
* `label` beginning with the `redis` tag
|
||||
* `uri` or `uris` using the scheme `redis`
|
||||
* `redisUri`, `redisuri`, `redisUrl`, or `redisurl` fields in `credentials`
|
||||
|
||||
==== SMTP
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `tags` including `smtp`
|
||||
* `label` beginning with the `smtp` tag
|
||||
* `uri` or `uris` using the scheme `smtp`
|
||||
* `smtpUri`, `smtpuri`, `smtpUrl`, or `smtpurl` fields in `credentials`
|
||||
|
||||
==== SQL Server
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* `uri` or `uris` using the scheme `sqlserver`
|
||||
* `jdbcUrl` field in `credentials` using the scheme `sqlserver`
|
||||
* `sqlserverUri`, `sqlserveruri`, `sqlserverUrl`, or `sqlserverurl` fields in `credentials`
|
||||
|
||||
== Supporting New Service Types
|
||||
|
||||
Extend `CloudFoundryServiceInfoCreator` with a creator for <<_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to `META-INF/service/org.springframework.cloud.cloudfoundry.CloudFoundryServiceInfoCreator`.
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
:toc: left
|
||||
:toclevels: 3
|
||||
|
||||
= Spring Cloud Connectors
|
||||
|
||||
@@ -10,15 +11,15 @@
|
||||
|
||||
== Introduction
|
||||
|
||||
Spring Cloud Connectors provides a simple abstraction for JVM-based applications running on cloud platforms to discover bound services and deployment information at runtime, and provides support for registering discovered services as Spring beans. It is based on a plugin model so that the identical compiled application can be deployed locally or on any of multiple cloud platforms, and it supports custom service definitions through Java SPI. The Connectors project provides out-of-the-box support for discovering common services on Heroku and Cloud Foundry clouds, as well as a properties-based connector that can supply configuration for development and testing.
|
||||
Spring Cloud Connectors provides a simple abstraction for JVM-based applications running on cloud platforms to discover bound services and deployment information at runtime, and provides support for registering discovered services as Spring beans. It is based on a plugin model so that the identical compiled application can be deployed locally or on any of multiple cloud platforms, and it supports custom service definitions through Java SPI.
|
||||
|
||||
For details on specific submodules and connectors, see <<Submodules>>.
|
||||
The Connectors project provides out-of-the-box support for discovering common services on Heroku and Cloud Foundry clouds. It also includes a properties-based connector that can supply configuration for development and testing.
|
||||
|
||||
=== Concepts
|
||||
|
||||
The core Connectors concepts are described below.
|
||||
|
||||
[width="100%"]
|
||||
[cols="3,7", width="100%"]
|
||||
|===========================================================================================================================================================================
|
||||
|**Cloud Connector** |A platform-specific interface that identifies the presence of the platform and discovers any services bound to the application deployment.
|
||||
|**Service Connector** |An object that represents a runtime connection to a service (for example, a `javax.sql.DataSource`).
|
||||
@@ -30,12 +31,12 @@ The core Connectors concepts are described below.
|
||||
|
||||
The project contains three major submodules.
|
||||
|
||||
* <<spring-cloud-core.adoc#,**Spring Cloud Connectors Core**>>: The core library, which is both cloud-agnostic and Spring-agnostic. It provides a programmatic entry point for developers who prefer to access cloud services and application information manually. It also provides basic service definitions for several common services (databases, message queues) and an SPI-based extension mechanism for contributing cloud and service connectors.
|
||||
* <<spring-cloud-spring-service-connector.adoc#,**Spring Cloud Spring Service Connector**>>: A Spring library that exposes application information, cloud information, and discovered services as Spring beans of the appropriate type. For example, an SQL service will be exposed as a `javax.sql.DataSource`, with optional connection pooling.
|
||||
* **Spring Cloud Connectors Core**: The core library, which is both cloud-agnostic and Spring-agnostic. It provides a programmatic entry point for developers who prefer to access cloud services and application information manually. It also provides basic service definitions for several common services (databases, message queues) and an SPI-based extension mechanism for contributing cloud and service connectors.
|
||||
* **Spring Cloud Spring Service Connector**: A Spring library that exposes application information, cloud information, and discovered services as Spring beans of the appropriate type (for example, an SQL service will be exposed as a `javax.sql.DataSource` with optional connection pooling).
|
||||
* The cloud connectors:
|
||||
** <<cloudfoundry-connector.adoc#,**Spring Cloud Cloud Foundry Connector**>>: Connector for link:http://cloudfoundry.org/[Cloud Foundry].
|
||||
** <<heroku-connector.adoc#,**Spring Cloud Heroku Connector**>>: Connector for link:https://www.heroku.com/[Heroku].
|
||||
** <<localconfig-connector.adoc#,**Spring Cloud local-configuration Connector**>>: Properties-based connector for manually providing configuration information during development or testing. Allows use of the same Spring Cloud configuration wiring in all stages of application deployment.
|
||||
** **Spring Cloud Cloud Foundry Connector**: Connector for link:http://cloudfoundry.org/[Cloud Foundry].
|
||||
** **Spring Cloud Heroku Connector**: Connector for link:https://www.heroku.com/[Heroku].
|
||||
** **Spring Cloud local-configuration Connector**: Properties-based connector for manually providing configuration information during development or testing. Allows use of the same Spring Cloud configuration wiring in all stages of application deployment.
|
||||
|
||||
== Getting Started
|
||||
|
||||
@@ -43,13 +44,13 @@ See below for examples of how to include the appropriate dependencies using your
|
||||
|
||||
=== Including Cloud Connectors
|
||||
|
||||
Include the connector for each cloud platform you want to be discoverable. Including multiple connectors is perfectly fine; each connector will determine whether it should be active in a particular environment.
|
||||
Include the connector for each cloud platform which you want to be discoverable. Including multiple connectors is perfectly fine; each connector will determine whether it should be active in a particular environment.
|
||||
|
||||
In Maven, replacing `${VERSION}` with the desired artifact version:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<!-- to use Spring Cloud Connectors for development -->
|
||||
<!-- To use Spring Cloud Connectors for development -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-localconfig-connector</artifactId>
|
||||
@@ -91,7 +92,7 @@ dependencies {
|
||||
|
||||
=== Spring Applications
|
||||
|
||||
If you're writing a Spring application, include the <<spring-cloud-spring-service-connector.adoc#,Spring Cloud Spring Service Connector>> dependency in addition to your cloud connector dependencies.
|
||||
If you're writing a Spring application, include the <<Spring Cloud Spring Service Connector>> dependency in addition to your cloud connector dependencies.
|
||||
|
||||
In Maven:
|
||||
|
||||
@@ -115,9 +116,194 @@ dependencies {
|
||||
}
|
||||
----
|
||||
|
||||
Then follow the instructions in the <<spring-cloud-spring-service-connector.adoc#,Spring Cloud Spring Service Connector>> documentation on Spring configuration <<spring-cloud-spring-service-connector.adoc#_the_java_config,using Java configuration>> or the <<spring-cloud-spring-service-connector.adoc#_the_code_cloud_code_namespace,`<cloud>` namespace>>.
|
||||
Then follow the instructions in the <<Spring Cloud Spring Service Connector>> documentation on Spring configuration <<_the_java_configuration,using Java configuration>> or the <<_the_code_cloud_code_namespace,`<cloud>` namespace>>.
|
||||
|
||||
=== Non-Spring Applications
|
||||
|
||||
The `spring-cloud-core` dependency is included by each cloud connector, so simply include the connectors for the platforms you want. Then follow the <<spring-cloud-core.adoc#,instructions on using the Spring Cloud Connectors API>>.
|
||||
The `spring-cloud-core` dependency is included by each cloud connector, so simply include the connectors for the platforms you want. Then follow the <<_spring_cloud_connectors_core,instructions on using the Spring Cloud Connectors API>>.
|
||||
|
||||
== Spring Cloud Connectors Core
|
||||
|
||||
This core library provides programmatic access to application and service information. This library has no Spring dependencies and may be used in non-Spring applications.
|
||||
|
||||
**This library requires Java 6 or newer.** It is cloud-agnostic; using the Java SPI, it supports pluggable cloud and service connectors. Support for Cloud Foundry and Heroku is available out-of-the-box, in addition to locally-provided configuration for development and testing.
|
||||
|
||||
=== Connecting to a Cloud
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If you are using Spring Cloud in a Spring application, you should consider <<_spring_cloud_spring_service_connector,automatically injecting Spring beans>> instead.
|
||||
====
|
||||
|
||||
* Include the desired cloud connectors on the runtime classpath, <<_getting_started,as described in the main documentation>>.
|
||||
|
||||
* Create a `CloudFactory` instance. Creation of a `CloudFactory` instance is a bit expensive, so we recommend using a singleton instance. If you are using a dependency injection framework such as Spring, create a bean for the `CloudFactory`.
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
CloudFactory cloudFactory = new CloudFactory();
|
||||
----
|
||||
|
||||
* Obtain the `Cloud` object for the environment in which the application is running.
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
Cloud cloud = cloudFactory.getCloud();
|
||||
----
|
||||
+
|
||||
Note that you must have a `CloudConnector` suitable for your deployment environment on your classpath. For example, if you are deploying the application to Cloud Foundry, you must add the <<_spring_cloud_cloud_foundry_connector,Cloud Foundry Connector>> to your classpath. If no suitable `CloudConnector` is found, the `getCloud()` method will throw a `CloudException`.
|
||||
|
||||
* Use the `Cloud` instance to access application and service information and to create service connectors.
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
// ServiceInfo has all the information necessary to connect to the underlying service
|
||||
List<ServiceInfo> serviceInfos = cloud.getServiceInfos();
|
||||
----
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
// Find the `ServiceInfo` definitions suitable for connecting to a particular service type
|
||||
List<ServiceInfo> databaseInfos = cloud.getServiceInfos(DataSource.class);
|
||||
----
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
// Alternatively, let Spring Cloud create a service connector for you
|
||||
String serviceId = "inventory-db";
|
||||
DataSource ds = cloud.getServiceConnector(serviceId, DataSource.class,
|
||||
null /* default config */);
|
||||
----
|
||||
|
||||
=== Adding Cloud Connectors
|
||||
|
||||
A cloud provider may extend Spring Cloud to make it work with a new cloud platform by adding a new `CloudConnector`. The connector is responsible for determining whether the application is running in the specific cloud, identifying application information (such as the name and instance ID of the particular running instance), and mapping bound services (such as URIs exposed in environment variables) as `ServiceInfo` objects.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
See the <<_spring_cloud_cloud_foundry_connector,Cloud Foundry Connector>> and <<_spring_cloud_heroku_connector,Heroku Connector>> for examples.
|
||||
====
|
||||
|
||||
Spring Cloud uses the Java SPI to discover available connectors. New cloud connectors should list the fully-qualified class name in the provider-configuration file at `META-INF/services/org.springframework.cloud.CloudConnector`.
|
||||
|
||||
=== Adding Service Discovery
|
||||
|
||||
To allow Spring Cloud to discover a new type of service (e.g. a `HelloWorldService`), create a `ServiceInfo` class containing the information necessary to connect to the service. If your service can be specified via a URI, extend `UriBasedServiceInfo` and provide the URI scheme in a call to the `super` constructor.
|
||||
|
||||
The following class will expose information for a service available at `helloworld://username:password@host:port/Bonjour`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
public class HelloWorldServiceInfo extends UriBasedServiceInfo {
|
||||
public static final String URI_SCHEME = "helloworld";
|
||||
|
||||
// Needed to support structured service definitions such as Cloud Foundry's
|
||||
public HelloWorldServiceInfo(String id, String host, int port, String username, String password, String greeting) {
|
||||
super(id, URI_SCHEME, host, port, username, password, greeting);
|
||||
}
|
||||
|
||||
// Needed to support URI-based service definitions such as Heroku's
|
||||
public HelloWorldServiceInfo(String id, String uri) {
|
||||
super(id, uri);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
After creating the `ServiceInfo` class, you will need to create a `ServiceInfoCreator` for each cloud platform you want to support. You will probably want to extend the appropriate creator base class(es), such as `HerokuServiceInfoCreator`. This is often as simple as writing a method that (in the case of the `HelloWorldService`) instantiates a new `HelloWorldServiceInfo`.
|
||||
|
||||
Register your `ServiceInfoCreator` classes in the appropriate provider-configuration file for your cloud's `ServiceInfoCreator` base class.
|
||||
|
||||
=== Adding Service Connectors
|
||||
|
||||
A service connector consumes a `ServiceInfo` discovered by the cloud connector and converts it into the appropriate service object, such as a `DataSource` in the case of a service definition that represents a SQL database.
|
||||
|
||||
Service connectors may be tightly bound to the framework whose service objects they are creating. For example, some connectors in the <<_spring_cloud_spring_service_connector,Spring Service Connector>> create connection factories defined by Spring Data, for use in building Spring Data templates.
|
||||
|
||||
To add new service connectors, implement `ServiceConnectorCreator` in your connector classes and list the fully-qualified class names in the provider-configuration file at `META-INF/services/org.springframework.cloud.service.ServiceConnectorCreator`.
|
||||
|
||||
== Spring Cloud Spring Service Connector
|
||||
|
||||
See <<spring-cloud-spring-service-connector.adoc#,Spring Cloud Spring Service Connector>>.
|
||||
|
||||
== Spring Cloud Cloud Foundry Connector
|
||||
|
||||
See <<spring-cloud-cloud-foundry-connector.adoc#,Spring Cloud Cloud Foundry Connector>>.
|
||||
|
||||
== Spring Cloud Heroku Connector
|
||||
|
||||
See <<spring-cloud-heroku-connector.adoc#,Spring Cloud Heroku Connector>>.
|
||||
|
||||
== Spring Cloud local-configuration Connector
|
||||
|
||||
This connector provides the ability to configure Spring Cloud services locally for development or testing. **The current implementation reads from Java properties only.**
|
||||
|
||||
=== Quick Start
|
||||
|
||||
Since service URIs contain passwords and should not be stored in code, this connector does not attempt to read service definitions out of the classpath. You can provide service definitions as system properties.
|
||||
|
||||
[source,term]
|
||||
----
|
||||
java -Dspring.cloud.database='mysql://user:pass@host:1234/dbname' -jar my-app.jar
|
||||
----
|
||||
|
||||
You can also provide service definitions from a configuration properties file, either by setting the `spring.cloud.propertiesFile` system property:
|
||||
|
||||
[source,term]
|
||||
----
|
||||
java -Dspring.cloud.propertiesFile=/path/to/spring-cloud.properties -jar my-app.jar
|
||||
----
|
||||
|
||||
or by providing the bootstrap properties file `spring-cloud-bootstrap.properties` on the runtime classpath. This file will be inspected only for the property named `spring.cloud.propertiesFile`, and its value will be interpolated from the system properties.
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.propertiesFile: ${user.home}/.config/myApp/spring-cloud.properties
|
||||
----
|
||||
|
||||
The system properties, or the configuration properties file, should contain an application ID and the desired services in the following format.
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
spring.cloud.appId: myApp
|
||||
; spring.cloud.{id}: URI
|
||||
spring.cloud.database: mysql://user:pass@host:1234/dbname
|
||||
----
|
||||
|
||||
The service type is determined by the URI scheme. The connector will activate if it finds a property (either in the system properties or in the configuration properties file) named `spring.cloud.appId`.
|
||||
|
||||
=== Property Sources
|
||||
|
||||
This connector first attempts to read the system properties generally and a system property named `spring.cloud.propertiesFile` specifically. If the system properties are not readable (if the security manager denies `checkPropertiesAccess`), then they will be treated as empty. If a system property named `spring.cloud.propertiesFile` is found, then that file will be loaded as a property list.
|
||||
|
||||
==== Providing a Bootstrap Properties File
|
||||
|
||||
To avoid having to manually configure run configurations or test runners with the path to the configuration properties file, the connector can read a templated filename out of the runtime classpath. This file must be named `spring-cloud-bootstrap.properties` and be located at the classpath root. For security, the connector will not attempt to read any service URIs out of the file. If the connector does find the file, it will read the property `spring.cloud.propertiesFile` and link:http://commons.apache.org/proper/commons-lang/javadocs/api-release/index.html?org/apache/commons/lang3/text/StrSubstitutor.html[substitute the pattern `${system.property}`] with the appropriate value from the system properties. The most useful option is generally `${user.home}`.
|
||||
|
||||
A configuration properties file specified in the system properties will override any bootstrap file that may be available on the classpath.
|
||||
|
||||
==== Property Precedence
|
||||
|
||||
To provide the maximum configuration flexibility, the connector will override any properties (both application ID and service definitions) specified in the file at `spring.cloud.propertiesFile` with system properties defined at runtime. The connector will log a message at `WARN` if you override a service ID.
|
||||
|
||||
=== Activating the Connector
|
||||
|
||||
Spring Cloud Core expects exactly one cloud connector to match the runtime environment. This connector identifies the “local cloud” by the presence of a property, in a configuration properties file or in the system properties, named `spring.cloud.appId`. This property will be used in the `ApplicationInstanceInfo`.
|
||||
|
||||
=== Service Definitions
|
||||
|
||||
If the connector is activated, it will iterate through all of the available properties for keys matching the pattern `spring.cloud.{serviceId}`. Each value is interpreted as a URI to a service, and the type of service is determined from the scheme. Every standard `UriBasedServiceInfo` is supported.
|
||||
|
||||
=== Supporting Additional Services
|
||||
|
||||
Extend `LocalConfigServiceInfoCreator` with a creator for <<_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to `META-INF/service/org.springframework.cloud.localconfig.LocalConfigServiceInfoCreator`.
|
||||
|
||||
=== Instance ID
|
||||
|
||||
This connector creates a UUID for use as the instance ID, as Java does not provide any portable mechanism for reliably determining hostnames or PIDs.
|
||||
|
||||
== Extending Spring Cloud Connectors
|
||||
|
||||
Coming soon...
|
||||
|
||||
|
||||
@@ -1,116 +0,0 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
|
||||
= Spring Cloud Connectors Core
|
||||
|
||||
[[spring-cloud-connectors-install]]
|
||||
|
||||
This core library provides programmatic access to application and service information. This library has no Spring dependencies and may be used in non-Spring applications.
|
||||
|
||||
This library requires Java 6 or newer.
|
||||
|
||||
This library is cloud-agnostic. Using Java SPI, it supports pluggable cloud and service connectors; support for Cloud Foundry and Heroku is available out-of-the-box, in addition to locally-provided configuration for development and testing.
|
||||
|
||||
== Connecting to a cloud
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If you are using Spring Cloud in a Spring application, you should consider <<spring-cloud-spring-service-connector.adoc#,automatically injecting Spring beans>> instead.
|
||||
====
|
||||
|
||||
* Include the desired cloud connectors on the runtime classpath <<spring-cloud-connectors.adoc#,as described in the main documentation>>.
|
||||
|
||||
* Create a `CloudFactory` instance. Creation of a `CloudFactory` instance is a bit expensive, so using a singleton instance is recommended. If you are using a dependency injection framework such as Spring, create a bean for the `CloudFactory`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
CloudFactory cloudFactory = new CloudFactory();
|
||||
----
|
||||
|
||||
* Obtain the `Cloud` object for the environment in which the application is running.
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
Cloud cloud = cloudFactory.getCloud();
|
||||
----
|
||||
+
|
||||
Note that you must have a `CloudConnector` suitable for your deployment environment on your classpath. For example, if you are deploying the application to Cloud Foundry, you must add the <<cloudfoundry-connector.adoc#,Cloud Foundry Connector>> to your classpath. If no suitable `CloudConnector` is found, the `getCloud()` method will throw a `CloudException`.
|
||||
|
||||
* Use the `Cloud` instance to access application and service information and to create service connectors.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// ServiceInfo has all the information necessary to connect to the underlying service
|
||||
List<ServiceInfo> serviceInfos = cloud.getServiceInfos();
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// find the `ServiceInfo` definitions suitable for connecting to a particular service type
|
||||
List<ServiceInfo> databaseInfos = cloud.getServiceInfos(DataSource.class);
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Alternately, let Spring Cloud create a service connector for you
|
||||
String serviceId = "inventory-db";
|
||||
DataSource ds = cloud.getServiceConnector(serviceId, DataSource.class, null /* default config */);
|
||||
----
|
||||
|
||||
== Adding cloud connectors
|
||||
|
||||
A cloud provider may extend Spring Cloud by adding a new `CloudConnector` to make Spring Cloud work with a new cloud platform. The connector is responsible for telling whether the application is running in the specific cloud, identifying application information (such as the name and instance ID of the particular running instance), and mapping bound services (such as URIs exposed in environment variables) as `ServiceInfo` objects.
|
||||
|
||||
See the <<cloudfoundry-connector.adoc#,Cloud Foundry Connector>> and <<heroku-connector.adoc#,Heroku Connector>> for examples.
|
||||
|
||||
Spring Cloud uses the Java SPI to discover available connectors. New cloud connectors should list the fully-qualified class name in the provider-configuration file at
|
||||
|
||||
----
|
||||
META-INF/services/org.springframework.cloud.CloudConnector
|
||||
----
|
||||
|
||||
== Adding service discovery
|
||||
|
||||
To allow Spring Cloud to discover a new type of service (`HelloWorldService`), create a `ServiceInfo` class containing the information necessary to connect to your service. If your service can be specified via a URI, extend `UriBasedServiceInfo` and provide the URI scheme in a call to the `super` constructor.
|
||||
|
||||
This class will expose information for a service available at
|
||||
|
||||
----
|
||||
helloworld://username:password@host:port/Bonjour
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
public class HelloWorldServiceInfo extends UriBasedServiceInfo {
|
||||
public static final String URI_SCHEME = "helloworld";
|
||||
|
||||
// needed to support structured service definitions like Cloud Foundry
|
||||
public HelloWorldServiceInfo(String id, String host, int port, String username, String password, String greeting) {
|
||||
super(id, URI_SCHEME, host, port, username, password, greeting);
|
||||
}
|
||||
|
||||
// needed to support URI-based service definitions like Heroku
|
||||
public HelloWorldServiceInfo(String id, String uri) {
|
||||
super(id, uri);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Then you will need to create a `ServiceInfoCreator` for each cloud platform you want to support. You will probably want to extend the appropriate creator base class(es), such as `HerokuServiceInfoCreator`. This is often as simple as writing a method that instantiates a new `HelloWorldServiceInfo`.
|
||||
|
||||
Register your `ServiceInfoCreator` classes in the appropriate provider-configuration file for your cloud's `ServiceInfoCreator` base class.
|
||||
|
||||
== Adding service connectors
|
||||
|
||||
A service connector consumes a `ServiceInfo` discovered by the cloud connector and converts it into the appropriate service object, such as a `DataSource` for a service definition representing a SQL database.
|
||||
|
||||
Service connectors may be tightly bound to the framework whose service objects they are creating; for example, some connectors in the <<spring-cloud-spring-service-connector.adoc#,Spring service connector>> create connection factories defined by Spring Data, for use in building Spring Data templates.
|
||||
|
||||
To add new service connectors, implement `ServiceConnectorCreator` in your connector classes and list the fully-qualified class names in the provider-configuration file at
|
||||
|
||||
----
|
||||
META-INF/services/org.springframework.cloud.service.ServiceConnectorCreator
|
||||
----
|
||||
93
docs/src/main/asciidoc/spring-cloud-heroku-connector.adoc
Normal file
93
docs/src/main/asciidoc/spring-cloud-heroku-connector.adoc
Normal file
@@ -0,0 +1,93 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-connectors
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
:toclevels: 3
|
||||
|
||||
= Spring Cloud Heroku Connector
|
||||
|
||||
The Heroku Connector is part of the <<spring-cloud-connectors.adoc#,Spring Cloud Connectors>> project.
|
||||
|
||||
This connector will discover services that are bound to an application running in Heroku.
|
||||
|
||||
== Cloud Detection
|
||||
|
||||
This connector checks for the presence of a `DYNO` environment variable. This variable is specific to and provided by Heroku; it is set to the identifier of an application’s dyno. If the variable exists, the connector will be activated.
|
||||
|
||||
== Service Detection
|
||||
|
||||
Heroku exposes the URL of a service instance (add-on) as a _config var_, which is made available to an application as an environment variable. The Spring Cloud Heroku Connector checks for environment variables which contain URLs used by add-ons and uses their presence to detect the relevant services.
|
||||
|
||||
As an example, consider a RabbitMQ service provided by CloudAMQP. After adding the CloudAMQP add-on to a Heroku application, you can run `heroku config` to see a new `CLOUDAMQP_URL` config var.
|
||||
|
||||
[source,term]
|
||||
----
|
||||
$ heroku config
|
||||
=== frozen-oasis-1234 Config Vars
|
||||
CLOUDAMQP_URL: amqp://sfdkjdj:6eknfh-4xlw1u6fec3@foo.bar.cloudamqp.com/lyfkue
|
||||
...
|
||||
----
|
||||
|
||||
=== Supported Services
|
||||
|
||||
This connector comes with built-in support for several service types and providers. The variables and URI schemes with which it establishes availability of each service are described below.
|
||||
|
||||
==== PostgreSQL (Heroku)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* a `HEROKU_POSTGRESQL_` config var with value using the scheme `postgres`
|
||||
|
||||
==== MySQL (ClearDB)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* a `CLEARDB_DATABASE_URL` config var with value using the scheme `mysql`
|
||||
|
||||
==== Redis (Redis To Go, Redis Cloud, RedisGreen, openredis)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* a `REDISTOGO_URL` config var with value using the scheme `redis`
|
||||
* a `REDISCLOUD_URL` config var with value using the scheme `redis`
|
||||
* an `OPENREDIS_URL` config var with value using the scheme `redis`
|
||||
* a `REDISGREEN_URL` config var with value using the scheme `redis`
|
||||
|
||||
==== MongoDB (MongoLab, MongoHQ, MongoSoup)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* a `MONGOLAB_URI` config var with value using the scheme `mongodb`
|
||||
* a `MONGOHQ_URL` config var with value using the scheme `mongodb`
|
||||
* a `MONGOSOUP_URL` config var with value using the scheme `mongodb`
|
||||
|
||||
==== RabbitMQ (CloudAMQP)
|
||||
|
||||
The connector will check for:
|
||||
|
||||
* a `CLOUDAMQP_URL` config var with value using the scheme `amqp` or `amqps`
|
||||
|
||||
== Supporting Additional Providers for Existing Service Types
|
||||
|
||||
To add support for a new provider of a service already listed above, add the provider's environment prefix to the list in `getEnvPrefixes()` on the `ServiceInfoCreator` class.
|
||||
|
||||
== Supporting New Service Types
|
||||
|
||||
Extend `HerokuServiceInfoCreator` with a creator for <<_adding_service_discovery,your service's `ServiceInfo` class>>.
|
||||
|
||||
Add the fully-qualified class name for your creator to `META-INF/service/org.springframework.cloud.heroku.HerokuServiceInfoCreator`.
|
||||
|
||||
== Limitations
|
||||
|
||||
Unlike Cloud Foundry, Heroku exposes very little application information that is retrievable from within a running instance (for example, there is no good way to find the name of the application). If your application requires access to such information, you must make the information available through environment variables.
|
||||
|
||||
To have a sensible application name available through `ApplicationInstanceInfo`, set the `SPRING_CLOUD_APP_NAME` environment variable.
|
||||
|
||||
[source,term]
|
||||
----
|
||||
heroku config:add SPRING_CLOUD_APP_NAME=myappname --app myappname
|
||||
----
|
||||
|
||||
If this environment variable is not set, the application name will be set to `<unknown>`.
|
||||
|
||||
@@ -3,22 +3,21 @@
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
:toc:
|
||||
:toclevels: 3
|
||||
|
||||
= Spring Cloud Spring Service Connector
|
||||
|
||||
[[spring-cloud-connectors-install]]
|
||||
The Spring Service Connector is part of the <<spring-cloud-connectors.adoc#,Spring Cloud Connectors>> project.
|
||||
|
||||
Provides `ServiceConnectorCreator` implementation for `javax.sql.DataSource` and various spring-data connector factories.
|
||||
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.
|
||||
|
||||
Also provides Java config and the XML namespace support for connecting to cloud services as well as accessing cloud services and application properties.
|
||||
== The Java Configuration
|
||||
|
||||
== The Java Config
|
||||
|
||||
Typical use of Java config involves extending the `AbstractCloudConfig` class and adding methods with the `@Bean` annotation to create beans for services. Apps migrating from link:https://spring.io/blog/2011/11/04/using-cloud-foundry-services-with-spring-part-2-auto-reconfiguration/[auto-reconfiguration] might first try the <<spring-cloud-spring-service-connector.adoc#_scanning_for_services,service-scanning approach>> until they need more explicit control. Java config also offers a way to expose application and service properties, should you choose to take a lower level access in creating service connectors yourself (or for debugging purposes, etc.).
|
||||
Typical use of the Java configuration involves extending the `AbstractCloudConfig` class and creating beans for services by annotating methods with the `@Bean` annotation. (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.) 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
|
||||
|
||||
In the following example, the configuration creates a `DataSource` bean connecting to the only relational database service bound to the app (it will fail if there is no such unique service). It also creates a `MongoDbFactory` bean, again, connecting to the only mongodb service bound to the app. Please check Javadoc for `AbstractCloudConfig` for ways to connect to other services.
|
||||
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`].)
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@@ -33,13 +32,20 @@ class CloudConfig extends AbstractCloudConfig {
|
||||
return connectionFactory().mongoDbFactory();
|
||||
}
|
||||
|
||||
//... more beans to obtain service connectors
|
||||
// (More beans to obtain service connectors)
|
||||
}
|
||||
----
|
||||
|
||||
The bean names will match the method names unless you specify an explicit value to the annotation such as `@Bean("inventory-service")` (this just follows how Spring's Java configuration works).
|
||||
You can specify a bean name by providing a value in the `@Bean` annotation.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean("inventory-service")
|
||||
----
|
||||
|
||||
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 app or want to have an explicit control over the services to which a bean is bound, you can pass the service names to methods such as `dataSource()` and `mongoDbFactory()` as follows:
|
||||
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]
|
||||
----
|
||||
@@ -54,19 +60,19 @@ class CloudConfig extends AbstractCloudConfig {
|
||||
return connectionFactory().mongoDbFactory("document-service");
|
||||
}
|
||||
|
||||
//... more beans to obtain service connectors
|
||||
// (More beans to obtain service connectors)
|
||||
}
|
||||
----
|
||||
|
||||
Method such as `dataSource()` come in a additional overloaded variant that offer specifying configuration options such as the pooling parameters. Please see Javadoc for more details.
|
||||
Methods such as `dataSource()` come in additional overloaded variants that let you specify configuration options (such as pooling parameters). See the relevant Javadocs for more information.
|
||||
|
||||
=== Connecting to Generic Services
|
||||
|
||||
Java config supports access to generic services (that don't have a directly mapped method--typical for a newly introduced service or connecting to a private service in private PaaS) through the `service()` method. It follows the same pattern as the `dataSource()` etc, except it allows supplying the connector type as an additional parameters.
|
||||
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.
|
||||
|
||||
=== Scanning for Services
|
||||
|
||||
You can scan for each bound service using the `@ServiceScan` annotation as follows (conceptually similar to the @ComponentScan annotation in Spring):
|
||||
You can scan for each bound service using the `@ServiceScan` annotation. (This is conceptually similar to Spring's `@ComponentScan` annotation.)
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@@ -76,14 +82,18 @@ class CloudConfig {
|
||||
}
|
||||
----
|
||||
|
||||
Here, one bean of the appropriate type (`DataSource` for a relational database service, for example) will be created. Each created bean will have the `id` matching the corresponding service name. You can then inject such beans using auto-wiring:
|
||||
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.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Autowired DataSource inventoryDb;
|
||||
----
|
||||
|
||||
If the app is bound to more than one services of a type, you can use the `@Qualifier` annotation supplying it the name of the service as in the following code:
|
||||
If the application is bound to more than one service of a given type, you can specify one by using the `@Qualifier` annotation and providing it with the name of the appropriate service.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Autowired @Qualifier("inventory-db") DataSource inventoryDb;
|
||||
@Autowired @Qualifier("shipping-db") DataSource shippingDb;
|
||||
@@ -91,7 +101,7 @@ If the app is bound to more than one services of a type, you can use the `@Quali
|
||||
|
||||
=== Accessing Service Properties
|
||||
|
||||
You can expose raw properties for all services and the app throught a bean as follows:
|
||||
You can expose raw properties for all services and for the application through a bean.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@@ -107,45 +117,61 @@ class CloudPropertiesConfig extends AbstractCloudConfig {
|
||||
|
||||
=== Setting Up
|
||||
|
||||
The `<cloud>` namespace offers a simple way for Spring application to connect to cloud services. To use this namespace, add a declaration for the cloud namespace:
|
||||
The `<cloud>` namespace offers a simple way for a Spring application to connect to cloud services.
|
||||
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:cloud="http://www.springframework.org/schema/cloud"
|
||||
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
|
||||
http://www.springframework.org/schema/cloud http://www.springframework.org/schema/cloud/spring-cloud.xsd">
|
||||
To use this namespace, add a declaration for it.
|
||||
|
||||
<!-- <cloud> namespace usage here -->
|
||||
[source,xml]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:cloud="http://www.springframework.org/schema/cloud"
|
||||
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
|
||||
http://www.springframework.org/schema/cloud http://www.springframework.org/schema/cloud/spring-cloud.xsd">
|
||||
|
||||
<!-- <cloud> namespace usage here -->
|
||||
----
|
||||
|
||||
=== Creating Service Beans
|
||||
|
||||
Each namespace element that creates a bean corresponding to a service follows the following pattern (example is for a relational service):
|
||||
A namespace element which creates a service bean conforms to the following pattern (in this example, the bean is for a relational database service).
|
||||
|
||||
<cloud:data-source id="inventory-db" service-name="inventory-db-service">
|
||||
<cloud:connection properties="sessionVariables=sql_mode='ANSI';characterEncoding=UTF-8"/>
|
||||
<cloud:pool pool-size="20" max-wait-time="200"/>
|
||||
</cloud>
|
||||
[source,xml]
|
||||
----
|
||||
<cloud:data-source id="inventory-db" service-name="inventory-db-service">
|
||||
<cloud:connection properties="sessionVariables=sql_mode='ANSI';characterEncoding=UTF-8"/>
|
||||
<cloud:pool pool-size="20" max-wait-time="200"/>
|
||||
</cloud>
|
||||
----
|
||||
|
||||
This creates a `javax.sql.DataSource` bean with the `inventory-db` id, binding it to `inventory-db-service`. The created `DataSource` bean is configured with connection and pool properties as specified in the nested elements.
|
||||
When the `id` attribute is not specified, the service name is used as the `id`. When the `service-name` is not specified, the bean is bound to the only service in the corresponding category (relational database, in this case). If no unique service is found, a runtime exception is thrown.
|
||||
The above example creates a `javax.sql.DataSource` bean with the id `inventory-db`. The bean is bound to the `inventory-db-service` and is configured with the `connection` and `pool` properties specified in the nested `<cloud:connection>` and `<cloud:pool>` elements.
|
||||
|
||||
Other namespace elements that create service connector include:
|
||||
If no `id` attribute is specified, the `id` is set to the service name. If no `service-name` is specified, the bean is bound to the only service in the corresponding category (in this case, a relational database). If no unique service is found, a runtime exception will be thrown.
|
||||
|
||||
<cloud:mongo-db-factory/>
|
||||
<cloud:redis-connection-factory/>
|
||||
<cloud:rabbit-connection-factory/>
|
||||
Other namespace elements which create service connectors include:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<cloud:mongo-db-factory/>
|
||||
<cloud:redis-connection-factory/>
|
||||
<cloud:rabbit-connection-factory/>
|
||||
----
|
||||
|
||||
=== Connecting to Generic Services
|
||||
|
||||
We also supports a generic `<cloud:service>` namespace to allow connecting to a service that doesn't have directly mapped element (typical for a newly introduced service or connecting to a private service in private PaaS). You must specify either the `connector-type` attribute (so that it can find a unique service matching that type) or the `service-name` attribute.
|
||||
Spring Service Connector also supports a generic `<cloud:service>` 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.
|
||||
|
||||
<cloud:service id="email" service-name="email-service" connector-type="com.something.EmailConnectory/>
|
||||
[source,xml]
|
||||
----
|
||||
<cloud:service id="email" service-name="email-service" connector-type="com.something.EmailConnectory" />
|
||||
----
|
||||
|
||||
=== Scanning for Services
|
||||
|
||||
Besides these element that create one bean per element, we also support the `<cloud:service-scan>` element in the same spirit as the `<context:component-scan>` element. It scans for all the services bound to the app and creates a bean corresponding to each service. Each created bean has id that matches the service name to allow the use of the @Qualifier annotation along with @Autowired when more than one bean of the same type is introduced.
|
||||
Besides these elements (which create only one bean per element), Spring Service Connector provides a `<cloud:service-scan>` element, in the same spirit as the `<context:component-scan>` element. It scans for all services bound to the application and creates a bean for each service. Each bean has an `id` matching the service name; this means that you can use the `@Qualifier` annotation along with `@Autowired` when there is more than one bean of the same type.
|
||||
|
||||
=== Accessing Service Properties
|
||||
|
||||
Lastly, we support `<cloud:properties>` that exposes properties for the app and services.
|
||||
Lastly, Spring Service Connector provides a `<cloud:properties>` element, which exposes properties for the application and for services.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user