diff --git a/cloudfoundry-connector.html b/cloudfoundry-connector.html new file mode 100644 index 0000000..dd657f6 --- /dev/null +++ b/cloudfoundry-connector.html @@ -0,0 +1,478 @@ + + + + + + + +Spring Cloud Cloud Foundry Connector + + + + + +
+
+
+
+

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 your service’s ServiceInfo class.

+
+
+

Add the fully-qualified class name for your creator to

+
+
+
+
META-INF/service/org.springframework.cloud.cloudfoundry.CloudFoundryServiceInfoCreator
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/heroku-connector.html b/heroku-connector.html new file mode 100644 index 0000000..a7b4c35 --- /dev/null +++ b/heroku-connector.html @@ -0,0 +1,496 @@ + + + + + + + +Spring Cloud Heroku Connector + + + + + +
+
+
+
+

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 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>.

+
+
+
+
+ + + \ No newline at end of file diff --git a/localconfig-connector.html b/localconfig-connector.html new file mode 100644 index 0000000..a3e9940 --- /dev/null +++ b/localconfig-connector.html @@ -0,0 +1,536 @@ + + + + + + + +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. 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.

+
+
+
+
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:

+
+
+
+
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 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 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.

+
+
+
+
+ + + \ No newline at end of file diff --git a/spring-cloud-connectors.html b/spring-cloud-connectors.html new file mode 100644 index 0000000..74901cd --- /dev/null +++ b/spring-cloud-connectors.html @@ -0,0 +1,568 @@ + + + + + + + +Spring Cloud Connectors + + + + + +
+
+
+
+

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 multiple clouds, and it supports custom service definitions through Java SPI.

+
+
+

Spring Cloud Connectors provides out-of-the-box support for discovering common services on Heroku and Cloud Foundry clouds as well as a properties-based configuration for development and testing.

+
+
+

The core concepts used in this project are:

+
+
+
    +
  • +

    Cloud connector: An interface specific to a cloud platform that identifies the presence of the platform and discovers any services bound to the application deployment.

    +
    • +
  • +

    Service connector: An object, such as a javax.sql.DataSource, that represents a runtime connection to a service.

    +
    • +
  • +

    Service information: Information about the underlying service such as host, port, and credentials.

    +
    • +
  • +

    Application information: Information about the application and the particular running instance.

    +
    • +
+
+
+

The project contains three major submodules:

+
+
+
    +
  • +

    core: The core library, cloud- and Spring-agnostic, that 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 to contribute cloud and service connectors.

    +
    • +
  • +

    spring-service-connector: A Spring Library that exposes application and cloud information and discovered services as Spring beans of the appropriate type. For example, SQL services will be exposed as javax.sql.DataSource s with optional connection pooling.

    +
    • +
  • +

    Cloud connectors:

    +
    +
      +
    • +

      cloudfoundry-connector: Connector for Cloud Foundry.

      +
      • +
    • +

      heroku-connector: Connector for Heroku.

      +
      • +
    • +

      localconfig-connector: Properties-based connector for manually providing configuration information for development or testing. Allows the use of the same Spring Cloud configuration wiring in all stages of application deployment.

      +
      • +
    +
    +
    • +
+
+
+
+
+

Getting Started

+
+
+

The following examples are written for Maven; simply include the appropriate dependencies for your build system.

+
+
+

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.

+
+
+
+
<!-- to use Spring Cloud Connectors for development -->
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-localconfig-connector</artifactId>
+    <version>1.1.1.RELEASE</version>
+</dependency>
+
+<!-- If you intend to deploy the app to Cloud Foundry -->
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-cloudfoundry-connector</artifactId>
+    <version>1.1.1.RELEASE</version>
+</dependency>
+
+<!-- If you intend to deploy the app to Heroku -->
+<dependency>
+  <groupId>org.springframework.cloud</groupId>
+  <artifactId>spring-cloud-heroku-connector</artifactId>
+  <version>1.1.1.RELEASE</version>
+</dependency>
+
+
+
+
+

Spring applications

+
+

Add the spring-service-connector in addition to your cloud connectors:

+
+
+
+
<dependency>
+  <groupId>org.springframework.cloud</groupId>
+  <artifactId>spring-cloud-spring-service-connector</artifactId>
+  <version>1.1.1.RELEASE</version>
+</dependency>
+
+<!-- to use Spring Cloud for development -->
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-localconfig-connector</artifactId>
+    <version>1.1.1.RELEASE</version>
+</dependency>
+
+<!-- If you intend to deploy the app to Cloud Foundry -->
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-cloudfoundry-connector</artifactId>
+    <version>1.1.1.RELEASE</version>
+</dependency>
+
+<!-- If you intend to deploy the app to Heroku -->
+<dependency>
+  <groupId>org.springframework.cloud</groupId>
+  <artifactId>spring-cloud-heroku-connector</artifactId>
+  <version>1.1.1.RELEASE</version>
+</dependency>
+
+
+
+

Then follow the instructions on Spring configuration using Java configuration or the <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 instructions on using the Spring Cloud Connectors API.

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/spring-cloud-core.html b/spring-cloud-core.html new file mode 100644 index 0000000..498414a --- /dev/null +++ b/spring-cloud-core.html @@ -0,0 +1,585 @@ + + + + + + + +Spring Cloud 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.

+
+
+

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 automatically injecting Spring beans instead.

+
+
+
+
+
    +
  • +

    Include the desired cloud connectors on the runtime classpath 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.

    +
    • +
+
+
+
+
CloudFactory cloudFactory = new CloudFactory();
+
+
+
+
    +
  • +

    Obtain the Cloud object for the environment in which the application is running.

    +
    +
    +
    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 cloudfoundry-connector to your classpath. If no suitable CloudConnctor is found, the getCloud() method will throw a CloudException.

    +
    +
    • +
  • +

    Use the Cloud instance to access application and service information and to create service connectors.

    +
    • +
+
+
+
+
// ServiceInfo has all the information necessary to connect to the underlying service
+List<ServiceInfo> serviceInfos = cloud.getServiceInfos();
+
+
+
+
+
// find the `ServiceInfo` definitions suitable for connecting to a particular service type
+List<ServiceInfo> databaseInfos = cloud.getServiceInfos(DataSource.class);
+
+
+
+
+
// 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 Cloud Foundry and Heroku connectors 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
+
+
+
+
+
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 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
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/spring-cloud-spring-service-connector.html b/spring-cloud-spring-service-connector.html new file mode 100644 index 0000000..f5a6d00 --- /dev/null +++ b/spring-cloud-spring-service-connector.html @@ -0,0 +1,621 @@ + + + + + + + +Spring Cloud Spring Service Connector + + + + + +
+
+
+
+

Provides ServiceConnectorCreator implementation for javax.sql.DataSource and various spring-data connector factories.

+
+
+

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 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 auto-reconfguration might first try the 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.).

+
+
+

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.

+
+
+
+
class CloudConfig extends AbstractCloudConfig {
+    @Bean
+        public DataSource inventoryDataSource() {
+            return connectionFactory().dataSource();
+        }
+
+    @Bean
+    public MongoDbFactory documentMongoDbFactory() {
+        return connectionFactory().mongoDbFactory();
+    }
+
+    //... 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).

+
+
+

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:

+
+
+
+
class CloudConfig extends AbstractCloudConfig {
+    @Bean
+    public DataSource inventoryDataSource() {
+        return connectionFactory().dataSource("inventory-db-service");
+    }
+
+    @Bean
+    public MongoDbFactory documentMongoDbFactory() {
+        return connectionFactory().mongoDbFactory("document-service");
+    }
+
+    //... 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.

+
+
+
+

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.

+
+
+
+

Scanning for Services

+
+

You can scan for each bound service using the @ServiceScan annotation as follows (conceptually similar to the @ComponentScan annotation in Spring):

+
+
+
+
@Configuration
+@ServiceScan
+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:

+
+
+
+
@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:

+
+
+
+
@Autowired @Qualifier("inventory-db") DataSource inventoryDb;
+@Autowired @Qualifier("shipping-db") DataSource shippingDb;
+
+
+
+
+

Accessing Service Properties

+
+

You can expose raw properties for all services and the app throught a bean as follows:

+
+
+
+
class CloudPropertiesConfig extends AbstractCloudConfig {
+    @Bean
+    public Properties cloudProperties() {
+        return properties();
+    }
+}
+
+
+
+
+
+
+

The <cloud> Namespace

+
+
+

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:

+
+
+
+
<?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):

+
+
+
+
<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.

+
+
+

Other namespace elements that create service connector include:

+
+
+
+
<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.

+
+
+
+
<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.

+
+
+
+

Accessing Service Properties

+
+

Lastly, we support <cloud:properties> that exposes properties for the app and services.

+
+
+
+
+
+ + + \ No newline at end of file