Shake up docs for new library layout

.gitignore

@@ -0,0 +1,18 @@
+/application.yml
+/application.properties
+asciidoctor.css
+*~
+.#*
+*#
+target
+bin
+_site/
+.classpath
+.project
+.settings
+.springBeans
+.DS_Store
+*.sw*
+*.iml
+.idea
+.factorypath

.travis.yml

@@ -11,7 +11,7 @@ before_install:
 - gem install asciidoctor
 install:
 - mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true
-#- ./docs/src/main/asciidoc/ghpages.sh
+- ./docs/src/main/asciidoc/ghpages.sh
 script:
 - '[ "${TRAVIS_PULL_REQUEST}" != "false" ] || mvn --settings .settings.xml deploy
   -nsu -Dmaven.test.redirectTestOutputToFile=true'

README.adoc

@@ -0,0 +1,6 @@
+// Do not edit this file (e.g. go instead to src/main/asciidoc)
+
+
+http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook[Cloud Native] is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building http://12factor.net/[12-factor Apps] in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required.
+
+Many of those features are covered by http://projects.spring.io/spring-boot[Spring Boot], which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the `ApplicationContext` of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).

docs/src/main/adoc/README.adoc

@@ -1,3 +0,0 @@
-= Spring Cloud Commons and Context
-
-Common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).

docs/src/main/asciidoc/README.adoc

@@ -0,0 +1 @@
+include::intro.adoc[]

docs/src/main/asciidoc/intro.adoc

@@ -0,0 +1,4 @@
+
+http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook[Cloud Native] is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building http://12factor.net/[12-factor Apps] in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required. 
+
+Many of those features are covered by http://projects.spring.io/spring-boot[Spring Boot], which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the `ApplicationContext` of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).

docs/src/main/asciidoc/spring-cloud-commons.adoc

@@ -1,99 +1,22 @@
-=== Environment Changes
+= Cloud Native Applications
+:toc:
 
-The application will listen for an `EnvironmentChangedEvent` and react
+include::intro.adoc[]
-to the change in a couple of standard ways (additional
-`ApplicationListeners` can be added as `@Beans` by the user in the
-normal way). When an `EnvironmentChangedEvent` is observed it will
-have a list of key values that have changed, and the application will
-use those to:
 
-* Re-bind any `@ConfigurationProperties` beans in the context
+== Spring Cloud Context: Application Context Services
-* Set the logger levels for any properties in `logging.level.*`
 
-Note that the Config Client does not by default poll for changes in
+Spring Boot has an opinionated view of how to build an application
-the `Environment`, and generally we would not recommend that approach
+with Spring: for instance it has conventional locations for common
-for detecting changes (although you could set it up with a
+configuration file, and endpoints for common management and monitoring
-`@Scheduled` annotation). If you have a scaled-out client application
+tasks. Spring Cloud builds on top of that and adds a few features that
-then it is better to broadcast the `EnvironmentChangedEvent` to all
+probably all components in a system would use or occasionally need.
-the instances instead of having them polling for changes (e.g. using
-the https://github.com/spring-cloud/spring-cloud-bus[Spring Cloud
-Bus]).
-
-The `EnvironmentChangedEvent` covers a large class of refresh use
-cases, as long as you can actually make a change to the `Environment`
-and publish the event (those APIs are public and part of core
-Spring). You can verify the changes are bound to
-`@ConfigurationProperties` beans by visiting the `/configprops`
-endpoint (normal Spring Boot Actuator feature). For instance a
-`DataSource` can have its `maxPoolSize` changed at runtime (the
-default `DataSource` created by Spring Boot is an
-`@ConfigurationProperties` bean) and grow capacity
-dynamically. Re-binding `@ConfigurationProperties` does not cover
-another large class of use cases, where you need more control over the
-refresh, and where you need a change to be atomic over the whole
-`ApplicationContext`. To address those concerns we have
-`@RefreshScope`.
-
-=== Refresh Scope
-
-A Spring `@Bean` that is marked as `@RefreshScope` will get special
-treatment when there is a configuration change. This addresses the
-problem of stateful beans that only get their configuration injected
-when they are initialized. For instance if a `DataSource` has open
-connections when the database URL is changed via the `Environment`, we
-probably want the holders of those connections to be able to complete
-what they are doing. Then the next time someone borrows a connection
-from the pool he gets one with the new URL.
-
-Refresh scope beans are lazy proxies that initialize when they are
-used (i.e. when a method is called), and the scope acts as a cache of
-initialized values. To force a bean to re-initialize on the next
-method call you just need to invalidate its cache entry.
-
-The `RefreshScope` is a bean in the context and it has a public method
-`refreshAll()` to refresh all beans in the scope by clearing the
-target cache. There is also a `refresh(String)` method to refresh an
-individual bean by name. This functionality is exposed in the
-`/refresh` endpoint (over HTTP or JMX).
-
-NOTE: `@RefreshScope` works (technically) on an `@Configuration`
-class, but it might lead to surprising behaviour: e.g. it does *not*
-mean that all the `@Beans` defined in that class are themselves
-`@RefreshScope`. Specifically, anything that depends on those beans
-cannot rely on them being updated when a refresh is initiated, unless
-it is itself in `@RefreshScope` (in which it will be rebuilt on a
-refresh and its dependencies re-injected, at which point they will be
-re-initialized from the refreshed `@Configuration`).
-
-=== Encryption and Decryption
-
-The Config Client has an `Environment` pre-processor for decrypting
-property values locally. It follows the same rules as the Config
-Server, and has the same external configuration via `encrypt.\*`. Thus
-you can use encrypted values in the form `{cipher}*` and as long as
-there is a valid key then they will be decrypted before the main
-application context gets the `Environment`. To use the encryption
-features in a client you need to include Spring Security RSA in your
-classpath (Maven co-ordinates
-"org.springframework.security:spring-security-rsa") and you also need
-the full strength JCE extensions in your JVM (google it and download
-from Oracle).
-
-=== Endpoints
-
-For a Spring Boot Actuator application there are some additional management endpoints:
-
-* POST to `/env` to update the `Environment` and rebind `@ConfigurationProperties` and log levels
-* `/refresh` for re-loading the boot strap context and refreshing the `@RefreshScope` beans
-* `/restart` for closing the `ApplicationContext` and restarting it (disabled by default)
-* `/pause` and `/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`)
 
 === The Bootstrap Application Context
 
-The Config Client operates by creating a "bootstrap" application
+A Spring Cloud application operates by creating a "bootstrap"
 context, which is a parent context for the main application. Out of
 the box it is responsible for loading configuration properties from
-the Config Server, and also decrypting properties in the local
+the external sources, and also decrypting properties in the local
 external configuration files. The two contexts share an `Environment`
 which is the source of external properties for any Spring
 application. Bootstrap properties are added with high precedence, so
@@ -255,3 +178,96 @@ org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomP
 then the "customProperty" `PropertySource` will show up in any
 application that includes that jar on its classpath.
 
+=== Environment Changes
+
+The application will listen for an `EnvironmentChangedEvent` and react
+to the change in a couple of standard ways (additional
+`ApplicationListeners` can be added as `@Beans` by the user in the
+normal way). When an `EnvironmentChangedEvent` is observed it will
+have a list of key values that have changed, and the application will
+use those to:
+
+* Re-bind any `@ConfigurationProperties` beans in the context
+* Set the logger levels for any properties in `logging.level.*`
+
+Note that the Config Client does not by default poll for changes in
+the `Environment`, and generally we would not recommend that approach
+for detecting changes (although you could set it up with a
+`@Scheduled` annotation). If you have a scaled-out client application
+then it is better to broadcast the `EnvironmentChangedEvent` to all
+the instances instead of having them polling for changes (e.g. using
+the https://github.com/spring-cloud/spring-cloud-bus[Spring Cloud
+Bus]).
+
+The `EnvironmentChangedEvent` covers a large class of refresh use
+cases, as long as you can actually make a change to the `Environment`
+and publish the event (those APIs are public and part of core
+Spring). You can verify the changes are bound to
+`@ConfigurationProperties` beans by visiting the `/configprops`
+endpoint (normal Spring Boot Actuator feature). For instance a
+`DataSource` can have its `maxPoolSize` changed at runtime (the
+default `DataSource` created by Spring Boot is an
+`@ConfigurationProperties` bean) and grow capacity
+dynamically. Re-binding `@ConfigurationProperties` does not cover
+another large class of use cases, where you need more control over the
+refresh, and where you need a change to be atomic over the whole
+`ApplicationContext`. To address those concerns we have
+`@RefreshScope`.
+
+=== Refresh Scope
+
+A Spring `@Bean` that is marked as `@RefreshScope` will get special
+treatment when there is a configuration change. This addresses the
+problem of stateful beans that only get their configuration injected
+when they are initialized. For instance if a `DataSource` has open
+connections when the database URL is changed via the `Environment`, we
+probably want the holders of those connections to be able to complete
+what they are doing. Then the next time someone borrows a connection
+from the pool he gets one with the new URL.
+
+Refresh scope beans are lazy proxies that initialize when they are
+used (i.e. when a method is called), and the scope acts as a cache of
+initialized values. To force a bean to re-initialize on the next
+method call you just need to invalidate its cache entry.
+
+The `RefreshScope` is a bean in the context and it has a public method
+`refreshAll()` to refresh all beans in the scope by clearing the
+target cache. There is also a `refresh(String)` method to refresh an
+individual bean by name. This functionality is exposed in the
+`/refresh` endpoint (over HTTP or JMX).
+
+NOTE: `@RefreshScope` works (technically) on an `@Configuration`
+class, but it might lead to surprising behaviour: e.g. it does *not*
+mean that all the `@Beans` defined in that class are themselves
+`@RefreshScope`. Specifically, anything that depends on those beans
+cannot rely on them being updated when a refresh is initiated, unless
+it is itself in `@RefreshScope` (in which it will be rebuilt on a
+refresh and its dependencies re-injected, at which point they will be
+re-initialized from the refreshed `@Configuration`).
+
+=== Encryption and Decryption
+
+The Config Client has an `Environment` pre-processor for decrypting
+property values locally. It follows the same rules as the Config
+Server, and has the same external configuration via `encrypt.\*`. Thus
+you can use encrypted values in the form `{cipher}*` and as long as
+there is a valid key then they will be decrypted before the main
+application context gets the `Environment`. To use the encryption
+features in a client you need to include Spring Security RSA in your
+classpath (Maven co-ordinates
+"org.springframework.security:spring-security-rsa") and you also need
+the full strength JCE extensions in your JVM (google it and download
+from Oracle).
+
+=== Endpoints
+
+For a Spring Boot Actuator application there are some additional management endpoints:
+
+* POST to `/env` to update the `Environment` and rebind `@ConfigurationProperties` and log levels
+* `/refresh` for re-loading the boot strap context and refreshing the `@RefreshScope` beans
+* `/restart` for closing the `ApplicationContext` and restarting it (disabled by default)
+* `/pause` and `/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`)
+
+== Spring Cloud Commons: Common Abstractions
+
+Patterns such as service discovery, load balancing and circuit breakers lend themselves to a common abstraction layer that can be consumed by all Spring Cloud clients, independent of the implementation (e.g. discovery via Eureka or Consul).

docs/src/main/ruby/generate_readme.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+base_dir = File.join(File.dirname(__FILE__),'../../..')
+src_dir = File.join(base_dir, "/src/main/asciidoc")
+require 'asciidoctor'
+require 'optparse'
+
+options = {}
+file = "#{src_dir}/README.adoc"
+
+OptionParser.new do |o|
+  o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' }
+  o.on('-h', '--help') { puts o; exit }
+  o.parse!
+end
+
+file = ARGV[0] if ARGV.length>0
+
+srcDir = File.dirname(file)
+out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n"
+doc = Asciidoctor.load_file file, safe: :safe, parse: false, attributes: 'allow-uri-read'
+out << doc.reader.read
+
+unless options[:to_file]
+  puts out
+else
+  File.open(options[:to_file],'w+') do |file|
+    file.write(out)
+  end
+end

spring-cloud-commons/.gitignore

@@ -1,13 +0,0 @@
-*~
-#*
-*#
-.#*
-.classpath
-.project
-.settings/
-.springBeans
-target/
-_site/
-.idea
-*.iml
-*.swp

spring-cloud-commons/.travis.yml

@@ -1,25 +0,0 @@
-sudo: false
-cache:
-  directories:
-    - $HOME/.m2
-language: java
-before_install:
-- git config user.name "$GIT_NAME"
-- git config user.email "$GIT_EMAIL"
-- git config credential.helper "store --file=.git/credentials"
-- echo "https://$GH_TOKEN:@github.com" > .git/credentials
-- gem install asciidoctor
-install:
-- mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true
-#- ./docs/src/main/asciidoc/ghpages.sh
-script:
-- '[ "${TRAVIS_PULL_REQUEST}" != "false" ] || mvn --settings .settings.xml deploy
-  -nsu -Dmaven.test.redirectTestOutputToFile=true'
-- '[ "${TRAVIS_PULL_REQUEST}" = "false" ] || mvn --settings .settings.xml install
-  -nsu -Dmaven.test.redirectTestOutputToFile=true'
-env:
-  global:
-  - GIT_NAME="Spencer Gibb"
-  - GIT_EMAIL=sgibb@pivotal.io
-  - CI_DEPLOY_USERNAME=sgibb
-  - secure: WPmrAQJQGBziwGFKwTiDRGrG1nuy9dvoWOQt7WKHW0RBqDbUpZgGeHq6OD2FcE86eRo+tPDihyunsWltei+sfq5bUECkGFQBLGffcTuxyu2j4lTByVazeYKa3en3j7nOiQjI99MqgCHrdyRwtS9EF1SnYXRuSZXwb0Ic8h4Zns4=

spring-cloud-context/.gitignore

@@ -1,13 +0,0 @@
-*~
-#*
-*#
-.#*
-.classpath
-.project
-.settings/
-.springBeans
-target/
-_site/
-.idea
-*.iml
-*.swp

spring-cloud-context/.settings.xml

@@ -1,60 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<settings>
-  <servers>
-	<server>
-	  <id>repo.spring.io</id>
-	  <username>${env.CI_DEPLOY_USERNAME}</username>
-	  <password>${env.CI_DEPLOY_PASSWORD}</password>
-	</server>
-  </servers>
-  <profiles>
-	<profile>
-	  <id>spring</id>
-	  <activation><activeByDefault>true</activeByDefault></activation>
-	  <repositories>
-		<repository>
-			<id>spring-snapshots</id>
-			<name>Spring Snapshots</name>
-			<url>http://repo.spring.io/libs-snapshot-local</url>
-			<snapshots>
-				<enabled>true</enabled>
-			</snapshots>
-		</repository>
-		<repository>
-			<id>spring-milestones</id>
-			<name>Spring Milestones</name>
-			<url>http://repo.spring.io/libs-milestone-local</url>
-			<snapshots>
-				<enabled>false</enabled>
-			</snapshots>
-		</repository>
-		<repository>
-			<id>spring-releases</id>
-			<name>Spring Releases</name>
-			<url>http://repo.spring.io/release</url>
-			<snapshots>
-				<enabled>false</enabled>
-			</snapshots>
-		</repository>
-	  </repositories>
-	  <pluginRepositories>
-		<pluginRepository>
-			<id>spring-snapshots</id>
-			<name>Spring Snapshots</name>
-			<url>http://repo.spring.io/libs-snapshot-local</url>
-			<snapshots>
-				<enabled>true</enabled>
-			</snapshots>
-		</pluginRepository>
-		<pluginRepository>
-			<id>spring-milestones</id>
-			<name>Spring Milestones</name>
-			<url>http://repo.spring.io/libs-milestone-local</url>
-			<snapshots>
-				<enabled>false</enabled>
-			</snapshots>
-		</pluginRepository>
-	  </pluginRepositories>
-    </profile>
-  </profiles>
-</settings>