From c560820a9ea452bcd734ded5cbbd42f3fa28554b Mon Sep 17 00:00:00 2001 From: Ben Klein Date: Mon, 3 Aug 2015 13:25:42 -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 | 174 +++++++++++---------- spring-cloud-core.html | 2 +- spring-cloud-spring-service-connector.html | 2 +- 6 files changed, 96 insertions(+), 88 deletions(-) diff --git a/cloudfoundry-connector.html b/cloudfoundry-connector.html index f427c56..1d1059e 100644 --- a/cloudfoundry-connector.html +++ b/cloudfoundry-connector.html @@ -512,7 +512,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/heroku-connector.html b/heroku-connector.html index f427c56..1d1059e 100644 --- a/heroku-connector.html +++ b/heroku-connector.html @@ -512,7 +512,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/localconfig-connector.html b/localconfig-connector.html index f427c56..1d1059e 100644 --- a/localconfig-connector.html +++ b/localconfig-connector.html @@ -512,7 +512,7 @@ table.CodeRay td.code>pre{padding:0} diff --git a/spring-cloud-connectors.html b/spring-cloud-connectors.html index ecc7373..0629a01 100644 --- a/spring-cloud-connectors.html +++ b/spring-cloud-connectors.html @@ -500,22 +500,28 @@ table.CodeRay td.code>pre{padding:0} .CodeRay .head .head{color:#f4f} - +

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.

+

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.

@@ -726,7 +752,7 @@ table.CodeRay td.code>pre{padding:0}

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.

@@ -736,7 +762,7 @@ table.CodeRay td.code>pre{padding:0}

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

+

Connecting to a Cloud

@@ -745,7 +771,7 @@ table.CodeRay td.code>pre{padding:0} @@ -754,7 +780,7 @@ 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.

    @@ -776,7 +802,7 @@ 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 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.

  • @@ -810,7 +836,7 @@ table.CodeRay td.code>pre{padding:0}

    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 Connector and Heroku Connector for examples.

    +

    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

    @@ -864,7 +890,7 @@ table.CodeRay td.code>pre{padding:0}

    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.

    +

    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

    @@ -886,7 +912,7 @@ table.CodeRay td.code>pre{padding:0}

    The Java Configuration

    -

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

    +

    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

    @@ -1084,8 +1110,8 @@ table.CodeRay td.code>pre{padding:0}

    Spring Cloud Cloud Foundry Connector

    -
    -

    This connector will discover services bound to an application running in Cloud Foundry. It currently knows about:

    +
    +

    This connector will discover services that are bound to an application running in Cloud Foundry. It currently knows about:

      @@ -1111,7 +1137,7 @@ table.CodeRay td.code>pre{padding:0}

      SMTP gateway

    • -

      application monitoring (New Relic)

      +

      Application monitoring (New Relic)

    @@ -1119,17 +1145,12 @@ table.CodeRay td.code>pre{padding:0}

    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

    +

    Supporting New Service Types

    -

    Extend CloudFoundryServiceInfoCreator with a creator for your service’s ServiceInfo class.

    +

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

    Add the fully-qualified class name for your creator to META-INF/service/org.springframework.cloud.cloudfoundry.CloudFoundryServiceInfoCreator.

    @@ -1137,8 +1158,8 @@ table.CodeRay td.code>pre{padding:0}

    Spring Cloud Heroku Connector

    -
    -

    This connector will discover services bound to an application running in Heroku. It currently knows about:

    +
    +

    This connector will discover services that are bound to an application running in Heroku. It currently knows about:

      @@ -1149,7 +1170,7 @@ table.CodeRay td.code>pre{padding:0}

      MySQL (ClearDB)

    • -

      Redis (RedisToGo, Redis Cloud, RedisGreen, openredis)

      +

      Redis (Redis To Go, Redis Cloud, RedisGreen, openredis)

    • MongoDB (MongoLab, MongoHQ, MongoSoup)

      @@ -1159,44 +1180,36 @@ table.CodeRay td.code>pre{padding:0}
    -
    -

    Pull requests for adding additional services are welcome.

    -
    -

    Supporting additional providers for existing service types

    +

    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.

    +

    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

    +

    Supporting New Service Types

    -

    Extend HerokuServiceInfoCreator with a creator for your service’s ServiceInfo class.

    +

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

    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.

    +

    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 sensible app name available through ApplicationInstanceInfo, set the SPRING_CLOUD_APP_NAME environment variable

    +

    To have a sensible application name available through ApplicationInstanceInfo, set the SPRING_CLOUD_APP_NAME environment variable.

    -
    heroku config:add SPRING_CLOUD_APP_NAME=myappname --app myappname
    +
    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>.

    +

    If this environment variable is not set, the application name will be set to <unknown>.

    @@ -1204,29 +1217,29 @@ table.CodeRay td.code>pre{padding:0}

    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.

    +
    +

    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

    +

    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

    +

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

    +

    You can also provide service definitions 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
    +
    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.

    +

    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.

    @@ -1234,7 +1247,7 @@ table.CodeRay td.code>pre{padding:0}
    -

    The system properties or the configuration properties file should contain an application ID and the desired services in this format:

    +

    The system properties, or the configuration properties file, should contain an application ID and the desired services in the following format.

    @@ -1244,54 +1257,49 @@ 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.

    +

    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

    +

    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.

    +

    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, that file will be loaded as a property list.

    -

    Providing a bootstrap properties file

    +

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

    +

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

    +

    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

    +

    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.

    +

    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

    +

    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.

    +

    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

    +

    Supporting Additional Services

    -

    Extend LocalConfigServiceInfoCreator with a creator for your service’s ServiceInfo class.

    +

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

    Add the fully-qualified class name for your creator to META-INF/service/org.springframework.cloud.localconfig.LocalConfigServiceInfoCreator.

    @@ -1305,7 +1313,7 @@ spring.cloud.database: mysql://user:pass@host:1234/dbname
    diff --git a/spring-cloud-core.html b/spring-cloud-core.html index f427c56..1d1059e 100644 --- a/spring-cloud-core.html +++ b/spring-cloud-core.html @@ -512,7 +512,7 @@ table.CodeRay td.code>pre{padding:0}
    diff --git a/spring-cloud-spring-service-connector.html b/spring-cloud-spring-service-connector.html index f427c56..1d1059e 100644 --- a/spring-cloud-spring-service-connector.html +++ b/spring-cloud-spring-service-connector.html @@ -512,7 +512,7 @@ table.CodeRay td.code>pre{padding:0}
    • -

    If you are using Spring Cloud in a Spring application, you should consider automatically injecting Spring beans instead.

    +

    If you are using Spring Cloud in a Spring application, you should consider automatically injecting Spring beans instead.