From 302e1b4f797570ea02079eb2827ecd71468a2ea7 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Thu, 10 Mar 2016 11:43:40 +0100 Subject: [PATCH] Sync docs from master to gh-pages --- ghpages.sh | 24 +- spring-cloud-zookeeper.html | 501 +++++++++++++++++++++++++++++++++++- 2 files changed, 509 insertions(+), 16 deletions(-) diff --git a/ghpages.sh b/ghpages.sh index 91905757..e1063ce3 100644 --- a/ghpages.sh +++ b/ghpages.sh @@ -12,13 +12,20 @@ if ! [ -d docs/target/generated-docs ]; then exit 0 fi +# Find name of current branch +################################################################### +branch=$TRAVIS_BRANCH +[ "$branch" == "" ] && branch=`git rev-parse --abbrev-ref HEAD` +target=. +if [ "$branch" != "master" ]; then target=./$branch; mkdir -p $target; fi + # Stash any outstanding changes ################################################################### git diff-index --quiet HEAD dirty=$? if [ "$dirty" != "0" ]; then git stash; fi -# Switch to gh-pages branch to sync it with master +# Switch to gh-pages branch to sync it with current branch ################################################################### git checkout gh-pages @@ -26,21 +33,22 @@ for f in docs/target/generated-docs/*; do file=${f#docs/target/generated-docs/*} if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then # Not ignored... - cp -rf $f . - git add -A $file + cp -rf $f $target + git add -A $target/$file fi done -git commit -a -m "Sync docs from master to gh-pages" +git add -A README.adoc || echo "No change to README.adoc" +git commit -a -m "Sync docs from $branch to gh-pages" || echo "Nothing committed" # Uncomment the following push if you want to auto push to -# the gh-pages branch whenever you commit to master locally. +# the gh-pages branch whenever you commit to branch locally. # This is a little extreme. Use with care! ################################################################### -git push origin gh-pages +git push origin gh-pages || echo "Cannot push gh-pages" -# Finally, switch back to the master branch and exit block -git checkout master +# Finally, switch back to the current branch and exit block +git checkout $branch if [ "$dirty" != "0" ]; then git stash pop; fi exit 0 diff --git a/spring-cloud-zookeeper.html b/spring-cloud-zookeeper.html index abddb989..8e52f583 100644 --- a/spring-cloud-zookeeper.html +++ b/spring-cloud-zookeeper.html @@ -409,9 +409,37 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b .show-for-print{display:inherit!important}} - +
@@ -421,9 +449,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b and binding to the Spring Environment and other Spring programming model idioms. With a few simple annotations you can quickly enable and configure the common patterns inside your application and build large distributed systems with Zookeeper based components. The -patterns provided include Service Discovery, Circuit Breaker and Configuration. -Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon) are provided by -integration with Spring Cloud Netflix.

+patterns provided include Service Discovery and Configuration. +Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker +(Hystrix) are provided by integration with Spring Cloud Netflix.

@@ -431,7 +459,7 @@ integration with Spring Cloud Netflix.

Install Zookeeper

-

TODO: document zookeeper installation

+

Please see the installation documentation for instructions on how to install Zookeeper.

@@ -439,7 +467,409 @@ integration with Spring Cloud Netflix.

Service Discovery with Zookeeper

-

TODO: document zookeeper service discovery

+

Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Curator(A java library for Zookeeper) provides Service Discovery services via Service Discovery Extension. Spring Cloud Zookeeper leverages this extension for service registration and discovery.

+
+
+

How to activate

+
+

Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-discovery will enable auto-configuration that will setup Spring Cloud Zookeeper Discovery.

+
+
+
+

Registering with Zookeeper

+
+

When a client registers with Zookeeper, it provides meta-data about itself such as host and port, id and name.

+
+
+

Example Zookeeper client:

+
+
+
+
@SpringBootApplication
+@EnableDiscoveryClient
+@RestController
+public class Application {
+
+    @RequestMapping("/")
+    public String home() {
+        return "Hello world";
+    }
+
+    public static void main(String[] args) {
+        new SpringApplicationBuilder(Application.class).web(true).run(args);
+    }
+
+}
+
+
+
+

(i.e. utterly normal Spring Boot app). If Zookeeper is located somewhere other than localhost:2181, the configuration is required to locate the server. Example:

+
+
+
application.yml
+
+
spring:
+  cloud:
+    zookeeper:
+      connect-string: localhost:2181
+
+
+
+ + + + + +
+
Caution
+		 +If you use Spring Cloud Zookeeper Config, the above values will need to be placed in bootstrap.yml instead of application.yml. +
+
+
+

The default service name, instance id and port, taken from the Environment, are ${spring.application.name}, the Spring Context ID and ${server.port} respectively.

+
+
+

@EnableDiscoveryClient makes the app into both a Zookeeper "service" (i.e. it registers itself) and a "client" (i.e. it can query Zookeeper to locate other services).

+
+
+
+

Using the DiscoveryClient

+
+

Spring Cloud has support for Feign (a REST client builder) and also Spring RestTemplate using the logical service names instead of physical URLs.

+
+
+

You can also use the org.springframework.cloud.client.discovery.DiscoveryClient which provides a simple API for discovery clients that is not specific to Netflix, e.g.

+
+
+
+
@Autowired
+private DiscoveryClient discoveryClient;
+
+public String serviceUrl() {
+    List<ServiceInstance> list = discoveryClient.getInstances("STORES");
+    if (list != null && list.size() > 0 ) {
+        return list.get(0).getUri().toString();
+    }
+    return null;
+}
+
+
+
+
+

Using the Zookeeper Dependencies

+
+

Spring Cloud Zookeeper gives you a possibility to provide dependencies of your application as properties. As dependencies you can understand other applications that are registered +in Zookeeper and which you would like to call via Feign (a REST client builder) +and also Spring RestTemplate.

+
+
+

You can also benefit from the Zookeeper Dependency Watchers functionality that lets you control and monitor what is the state of your dependencies and decide what to do with that.

+
+
+
+

How to activate Zookeeper Dependencies

+
+
    +
  • +

    Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-discovery will enable auto-configuration that will setup Spring Cloud Zookeeper Dependencies.

    +
    • +
  • +

    In addition to that you have to set the property spring.cloud.zookeeper.dependencies.enabled to true (defaults to true if not set explicitly).

    +
    • +
  • +

    You have to have the spring.cloud.zookeeper.dependencies section properly set up - check the subsequent section for more details.

    +
    • +
+
+
+
+

Setting up Zookeeper Dependencies

+
+

Let’s take a closer look at an example of dependencies representation:

+
+
+
application.yml
+
+
spring.application.name: yourServiceName
+spring.cloud.zookeeper:
+  dependencies:
+    newsletter:
+      path: /path/where/newsletter/has/registered/in/zookeeper
+      loadBalancerType: ROUND_ROBIN
+      contentTypeTemplate: application/vnd.newsletter.$version+json
+      version: v1
+      headers:
+        header1:
+            - value1
+        header2:
+            - value2
+      required: false
+      stubs: org.springframework:foo:stubs
+    mailing:
+      path: /path/where/mailing/has/registered/in/zookeeper
+      loadBalancerType: ROUND_ROBIN
+      contentTypeTemplate: application/vnd.mailing.$version+json
+      version: v1
+      required: true
+
+
+
+

Let’s now go through each part of the dependency one by one. The root property name is spring.cloud.zookeeper.dependencies.

+
+
+

Aliases

+
+

Below the root property you have to represent each dependency has by an alias due to the constraints of Ribbon (the application id has to be placed in the URL +thus you can’t pass any complex path like /foo/bar/name). The alias will be the name that you will use instead of serviceId for DiscoveryClient, Feign or RestTemplate.

+
+
+

In the aforementioned examples the aliases are newsletter and mailing. Example of Feign usage with newsletter would be:

+
+
+
+
@FeignClient("newsletter")
+public interface NewsletterService {
+        @RequestMapping(method = RequestMethod.GET, value = "/newsletter")
+        String getNewsletters();
+}
+
+
+
+
+

Path

+
+

Represented by path yaml property.

+
+
+

Path is the path under which the dependency is registered under Zookeeper. Like presented before Ribbon operates on URLs thus this path is not compliant with its requirement. +That is why Spring Cloud Zookeeper maps the alias to the proper path.

+
+
+
+

Load balancer type

+
+

Represented by loadBalancerType yaml property.

+
+
+

If you know what kind of load balancing strategy has to be applied when calling this particular dependency then you can provide it in the yaml file and it will be automatically applied. +You can choose one of the following load balancing strategies

+
+
+
    +
  • +

    STICKY - once chosen the instance will always be called

    +
    • +
  • +

    RANDOM - picks an instance randomly

    +
    • +
  • +

    ROUND_ROBIN - iterates over instances over and over again

    +
    • +
+
+
+
+

Content-Type template and version

+
+

Represented by contentTypeTemplate and version yaml property.

+
+
+

If you version your api via the Content-Type header then you don’t want to add this header to each of your requests. Also if you want to call a new version of the API you don’t want to +roam around your code to bump up the API version. That’s why you can provide a contentTypeTemplate with a special $version placeholder. That placeholder will be filled by the value of the +version yaml property. Let’s take a look at an example.

+
+
+

Having the following contentTypeTemplate:

+
+
+
+
application/vnd.newsletter.$version+json
+
+
+
+

and the following version:

+
+
+
+
v1
+
+
+
+

Will result in setting up of a Content-Type header for each request:

+
+
+
+
application/vnd.newsletter.v1+json
+
+
+
+
+

Default headers

+
+

Represented by headers map in yaml

+
+
+

Sometimes each call to a dependency requires setting up of some default headers. In order not to do that in code you can set them up in the yaml file. +Having the following headers section:

+
+
+
+
headers:
+    Accept:
+        - text/html
+        - application/xhtml+xml
+    Cache-Control:
+        - no-cache
+
+
+
+

Results in adding the Accept and Cache-Control headers with appropriate list of values in your HTTP request.

+
+
+
+

Obligatory dependencies

+
+

Represented by required property in yaml

+
+
+

If one of your dependencies is required to be up and running when your application is booting then it’s enough to set up the required: true property in the yaml file.

+
+
+

If your application can’t localize the required dependency during boot time it will throw an exception and the Spring Context will fail to set up. +In other words your application won’t be able to start if the required dependency is not registered in Zookeeper.

+
+
+

You can read more about Spring Cloud Zookeeper Presence Checker in the following sections.

+
+
+
+
+

Stubs

+
+

You can provide a colon separated path to the JAR containing stubs of the dependency. Example

+
+
+
+
stubs: org.springframework:foo:stubs
+
+
+
+

means that for a particular dependencies can be found under:

+
+
+
    +
  • +

    groupId: org.springframework

    +
    • +
  • +

    artifactId: foo

    +
    • +
  • +

    classifier: stubs - this is the default value

    +
    • +
+
+
+

This is actually equal to

+
+
+
+
stubs: org.springframework:foo
+
+
+
+

since stubs is the default classifier.

+
+
+
+

Configuring Spring Cloud Zookeeper Dependencies

+
+

There is a bunch of properties that you can set to enable / disable parts of Zookeeper Dependencies functionalities.

+
+
+
    +
  • +

    spring.cloud.zookeeper.dependencies - if you don’t set this property you won’t benefit from Zookeeper Dependencies

    +
    • +
  • +

    spring.cloud.zookeeper.dependencies.ribbon.enabled (enabled by default) - Ribbon requires explicit global configuration or a particular one for a dependency. By turning on this property +runtime load balancing strategy resolution is possible and you can profit from the loadBalancerType section of the Zookeeper Dependencies. The configuration that needs this property +has an implementation of LoadBalancerClient that delegates to the ILoadBalancer presented in the next bullet

    +
    • +
  • +

    spring.cloud.zookeeper.dependencies.ribbon.loadbalancer (enabled by default) - thanks to this property the custom ILoadBalancer knows that the part of the URI passed to Ribbon might +actually be the alias that has to be resolved to a proper path in Zookeeper. Without this property you won’t be able to register applications under nested paths.

    +
    • +
  • +

    spring.cloud.zookeeper.dependencies.headers.enabled (enabled by default) - this property registers such a RibbonClient that automatically will append appropriate headers and content +types with version as presented in the Dependency configuration. Without this setting of those two parameters will not be operational.

    +
    • +
  • +

    spring.cloud.zookeeper.dependencies.resttemplate.enabled (enabled by default) - when enabled will modify the request headers of @LoadBalanced annotated RestTemplate so that it passes +headers and content type with version set in Dependency configuration. Wihtout this setting of those two parameters will not be operational.

    +
    • +
+
+
+
+

Spring Cloud Zookeeper Dependency Watcher

+
+

The Dependency Watcher mechanism allows you to register listeners to your dependencies. The functionality is in fact an implementation of the Observator pattern. When a dependency changes +its state (UP or DOWN) then some custom logic can be applied.

+
+
+
+

How to activate

+
+

Spring Cloud Zookeeper Dependencies functionality needs to be enabled to profit from Dependency Watcher mechanism.

+
+
+
+

Registering a listener

+
+

In order to register a listener you have to implement an interface org.springframework.cloud.zookeeper.discovery.watcher.DependencyWatcherListener and register it as a bean. +The interface gives you one method:

+
+
+
+
    /**
+    * Method executed upon state change of a dependency
+    *
+    * @param dependencyName - alias from microservice configuration {@see ZookeeperDependencies}
+    * @param newState
+    */
+    void stateChanged(String dependencyName, DependencyState newState);
+
+
+
+

If you want to register a listener for a particular dependency then the dependencyName would be the discriminator for your concrete implementation. newState will provide you with information + whether your dependency has changed to CONNECTED or DISCONNECTED.

+
+
+
+

Presence Checker

+
+

Bound with Dependency Watcher is the functionality called Presence Checker. It allows you to provide custom behaviour upon booting of your application to react accordingly to the state +of your dependencies.

+
+
+

The default implementation of the abstract org.springframework.cloud.zookeeper.discovery.watcher.presence.DependencyPresenceOnStartupVerifier class is the +org.springframework.cloud.zookeeper.discovery.watcher.presence.DefaultDependencyPresenceOnStartupVerifier which works in the following way.

+
+
+
    +
  • +

    If the dependency is marked us required and it’s not in Zookeeper then upon booting your application will throw an exception and shutdown

    +
    • +
  • +

    If dependency is not required the org.springframework.cloud.zookeeper.discovery.watcher.presence.LogMissingDependencyChecker will log that application is missing at WARN level

    +
    • +
+
+
+

The functionality can be overriden since the DefaultDependencyPresenceOnStartupVerifier is registered only when there is no bean of DependencyPresenceOnStartupVerifier.

+
@@ -447,14 +877,69 @@ integration with Spring Cloud Netflix.

Distributed Configuration with Zookeeper

-

TODO: document zookeeper config

+

Zookeeper provides a hierarchical namespace that allows clients to store arbitrary data, such as configuration data. Spring Cloud Zookeeper Config is an alternative to the Config Server and Client. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the /config namespace by default. Multiple PropertySource instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:

+
+
+
+
config/testApp,dev
+config/testApp
+config/application,dev
+config/application
+
+
+
+

The most specific property source is at the top, with the least specific at the bottom. Properties is the config/application namespace are applicable to all applications using zookeeper for configuration. Properties in the config/testApp namespace are only available to the instances of the service named "testApp".

+
+
+

Configuration is currently read on startup of the application. Sending a HTTP POST to /refresh will cause the configuration to be reloaded. Watching the configuration namespace (which Zookeeper supports) is not currently implemented, but will be a future addition to this project.

+
+
+

How to activate

+
+

Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-config will enable auto-configuration that will setup Spring Cloud Zookeeper Config.

+
+
+
+

Customizing

+
+

Zookeeper Config may be customized using the following properties:

+
+
+
bootstrap.yml
+
+
spring:
+  cloud:
+    zookeeper:
+      config:
+        enabled: true
+        root: configuration
+        defaultContext: apps
+        profileSeparator: '::'
+
+
+
+
    +
  • +

    enabled setting this value to "false" disables Zookeeper Config

    +
    • +
  • +

    root sets the base namespace for configuration values

    +
    • +
  • +

    defaultContext sets the name used by all applications

    +
    • +
  • +

    profileSeparator sets the value of the separator used to separate the profile name in property sources with profiles

    +
    • +
+