From 4cf3d3f66b96c3147753e80e2f728091381cfa14 Mon Sep 17 00:00:00 2001 From: Ben Klein Date: Fri, 31 Jul 2015 16:21:45 -0500 Subject: [PATCH] Sync docs from master to gh-pages --- cloudfoundry-connector.html | 2 +- heroku-connector.html | 2 +- localconfig-connector.html | 2 +- spring-cloud-connectors.html | 2 +- spring-cloud-core.html | 100 ++++++++---------- spring-cloud-spring-service-connector.html | 114 +++++++++++---------- 6 files changed, 111 insertions(+), 111 deletions(-) diff --git a/cloudfoundry-connector.html b/cloudfoundry-connector.html index d4e2f57..d9dbc2e 100644 --- a/cloudfoundry-connector.html +++ b/cloudfoundry-connector.html @@ -568,7 +568,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/heroku-connector.html b/heroku-connector.html index 236c444..f102329 100644 --- a/heroku-connector.html +++ b/heroku-connector.html @@ -588,7 +588,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/localconfig-connector.html b/localconfig-connector.html index a13d1fe..1219adb 100644 --- a/localconfig-connector.html +++ b/localconfig-connector.html @@ -636,7 +636,7 @@ spring.cloud.database: mysql://user:pass@host:1234/dbname diff --git a/spring-cloud-connectors.html b/spring-cloud-connectors.html index 729a3ad..9cfb8c2 100644 --- a/spring-cloud-connectors.html +++ b/spring-cloud-connectors.html @@ -698,7 +698,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/spring-cloud-core.html b/spring-cloud-core.html index ebd9eb5..65659e4 100644 --- a/spring-cloud-core.html +++ b/spring-cloud-core.html @@ -506,10 +506,10 @@ table.CodeRay td.code>pre{padding:0}
Table of Contents
@@ -517,18 +517,15 @@ table.CodeRay td.code>pre{padding:0}
-

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 core library provides programmatic access to application and service information. It 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.

+

This library requires Java 6 or newer. It is cloud-agnostic, supports pluggable cloud and service connectors using Java SPI, and provides support for Cloud Foundry and Heroku out-of-the-box, with locally-provided configuration available for development and testing.

-

Connecting to a cloud

+

Connecting to a Cloud

@@ -547,20 +544,16 @@ table.CodeRay td.code>pre{padding:0}
  • -

    Include the desired cloud connectors on the runtime classpath as described in the main documentation.

    +

    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.

    -
    • -
-
+

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.

CloudFactory cloudFactory = new CloudFactory();
-
-
    +

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

    @@ -569,79 +562,81 @@ table.CodeRay td.code>pre{padding:0}
-

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 Cloud Foundry Connector to your classpath. If no suitable CloudConnector is found, the getCloud() method will throw a CloudException.

+

Note that your classpath must have a CloudConnector suitable for your deployment environment---for example, if you are deploying the application to Cloud Foundry, you must add the Cloud Foundry Connector to your classpath. If the getCloud() method finds no suitable CloudConnector, it 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
+
    // ServiceInfo has all of 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
+
    // 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
+
    // Alternatively, let Spring Cloud create a service connector for you
 String serviceId = "inventory-db";
-DataSource ds = cloud.getServiceConnector(serviceId, DataSource.class, null /* default config */);
    
+DataSource ds = cloud.getServiceConnector(serviceId, DataSource.class,
+                                          null /* default config */);
    + + +
    -

    Adding cloud connectors

    +

    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.

    +

    A cloud provider may extend Spring Cloud by adding a new CloudConnector that tells Spring Cloud how to work with a new cloud platform. 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 Cloud Foundry Connector and 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
    -
    +

    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

    +

    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.

    +

    To allow Spring Cloud to discover a new type of service, 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
    -
    +

    Consider an example HelloWorldService. The following 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
+  // 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 like Heroku
+    // Needed to support URI-based service definitions such as Heroku's
     public HelloWorldServiceInfo(String id, String uri) {
         super(id, uri);
     }
@@ -649,36 +644,31 @@ table.CodeRay td.code>pre{padding:0}
    -

    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.

    +

    Next, create a ServiceInfoCreator for each cloud platform that 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 (for example, in the case of the HelloWorldService) 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.

    +

    Finally, register your ServiceInfoCreator classes in the appropriate provider-configuration file for your cloud’s ServiceInfoCreator base class.

    -

    Adding service connectors

    +

    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.

    +

    A service connector consumes a ServiceInfo discovered by the cloud connector and converts it into the appropriate service object (such as, in the case of a service definition representing a SQL database, a DataSource).

    -

    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.

    +

    Service connectors may be tightly bound to the framework whose service objects they are creating. For example, in the Spring Service Connector library, some connectors 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
    -
    +

    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.

    diff --git a/spring-cloud-spring-service-connector.html b/spring-cloud-spring-service-connector.html index f0ebe6b..c0c48de 100644 --- a/spring-cloud-spring-service-connector.html +++ b/spring-cloud-spring-service-connector.html @@ -506,7 +506,7 @@ table.CodeRay td.code>pre{padding:0}
    Table of Contents
      -
    • The Java Config +
    • The Java Configuration
      • Creating Service Beans
      • Connecting to Generic Services
        • @@ -530,23 +530,20 @@ table.CodeRay td.code>pre{padding:0}
        -

        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.

        +

        This library provides ServiceConnectorCreator implementations for javax.sql.DataSource and various 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 Config

        +

        The Java Configuration

        -

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

        +

        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 auto-reconfiguration, you might first try the 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 Javadoc for AbstractCloudConfig.)

        @@ -566,10 +563,18 @@ table.CodeRay td.code>pre{padding:0}
        -

        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.

        +
        +
        +
        +
        @Bean("inventory-service")
        +
        -

        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:

        +

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

        @@ -584,24 +589,24 @@ table.CodeRay td.code>pre{padding:0} 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 which 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.)

        @@ -612,27 +617,30 @@ table.CodeRay td.code>pre{padding:0}
        -

        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.

        -
        @Autowired DataSource inventoryDb;
        +
        @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 use the @Qualifier annotation, providing it with the name of the appropriate service.

        -
        @Autowired @Qualifier("inventory-db") DataSource inventoryDb;
-@Autowired @Qualifier("shipping-db") DataSource shippingDb;
        +
        @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:

        +

        You can expose raw properties for all services and for the application through a bean.

        @@ -653,73 +661,75 @@ table.CodeRay td.code>pre{padding:0}

        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.

        -
        +
        +

        To use this namespace, add a declaration for it.

        +
        +
        -
        <?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 -->
        +
        <?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 being created 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>
        +
        <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.

        -
        +
        +

        Other namespace elements which create service connectors include:

        +
        +
        -
        <cloud:mongo-db-factory/>
-<cloud:redis-connection-factory/>
-<cloud:rabbit-connection-factory/>
        +
        <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/>
        +
         <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.

        @@ -727,7 +737,7 @@ When the id attribute is not specified, the service name is used as