From 3369032a87b94f5b7924d1f2a2966acae62fbf47 Mon Sep 17 00:00:00 2001 From: Olga Maciaszek-Sharma Date: Thu, 4 Mar 2021 10:55:55 +0100 Subject: [PATCH] Add a quickstart section (#285) --- README.adoc | 228 +++++++++++++++++- docs/src/main/asciidoc/README.adoc | 4 + docs/src/main/asciidoc/quickstart.adoc | 223 +++++++++++++++++ .../main/asciidoc/spring-cloud-zookeeper.adoc | 4 + 4 files changed, 458 insertions(+), 1 deletion(-) create mode 100644 docs/src/main/asciidoc/quickstart.adoc diff --git a/README.adoc b/README.adoc index dc107582..680ba7b7 100644 --- a/README.adoc +++ b/README.adoc @@ -50,6 +50,232 @@ with Spring Cloud Netflix provides Intelligent Routing (Zuul), Client Side Load :sc-ext: java :project-full-name: Spring Cloud Zookeeper +== Quick Start + +This quick start walks through using Spring Cloud Zookeeper for Service Discovery and Distributed Configuration. + +First, run Zookeeper on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Zookeeper. + +=== Discovery Client Usage + +To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-discovery`. +The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-discovery`. +We recommend using dependency management and `spring-boot-starter-parent`. +The following example shows a typical Maven configuration: + +[source,xml,indent=0] +.pom.xml +---- + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + + + org.springframework.cloud + spring-cloud-starter-zookeeper-discovery + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + org.springframework.cloud + spring-cloud-dependencies + ${spring-cloud.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +---- + +The following example shows a typical Gradle setup: + +[source,groovy,indent=0] +.build.gradle +---- +plugins { + id 'org.springframework.boot' version ${spring-boot-version} + id 'io.spring.dependency-management' version ${spring-dependency-management-version} + id 'java' +} + +repositories { + mavenCentral() +} + +dependencies { + implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-discovery' + testImplementation 'org.springframework.boot:spring-boot-starter-test' +} +dependencyManagement { + imports { + mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}" + } +} +---- + +Now you can create a standard Spring Boot application, such as the following HTTP server: + +---- +@SpringBootApplication +@RestController +public class Application { + + @GetMapping("/") + public String home() { + return "Hello World!"; + } + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + +} +---- + +When this HTTP server runs, it connects to Zookeeper, which runs on the default local port (2181). +To modify the startup behavior, you can change the location of Zookeeper by using `application.properties`, as shown in the following example: + +---- +spring: + cloud: + zookeeper: + connect-string: localhost:2181 +---- + +You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate`, or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Zookeeper, as shown in the following example: + +[source,java,indent=0] +---- +@Autowired +private DiscoveryClient discoveryClient; + +public String serviceUrl() { + List list = discoveryClient.getInstances("STORES"); + if (list != null && list.size() > 0 ) { + return list.get(0).getUri().toString(); + } + return null; +} +---- + +=== Distributed Configuration Usage + +To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-config`. +The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-config`. +We recommend using dependency management and `spring-boot-starter-parent`. +The following example shows a typical Maven configuration: + +[source,xml,indent=0] +.pom.xml +---- + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + + + org.springframework.cloud + spring-cloud-starter-zookeeper-config + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + org.springframework.cloud + spring-cloud-dependencies + ${spring-cloud.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +---- + +The following example shows a typical Gradle setup: + +[source,groovy,indent=0] +.build.gradle +---- +plugins { + id 'org.springframework.boot' version ${spring-boot-version} + id 'io.spring.dependency-management' version ${spring-dependency-management-version} + id 'java' +} + +repositories { + mavenCentral() +} + +dependencies { + implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-config' + testImplementation 'org.springframework.boot:spring-boot-starter-test' +} +dependencyManagement { + imports { + mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}" + } +} +---- + +Now you can create a standard Spring Boot application, such as the following HTTP server: + +---- +@SpringBootApplication +@RestController +public class Application { + + @GetMapping("/") + public String home() { + return "Hello World!"; + } + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + +} +---- + +The application retrieves configuration data from Zookeeper. + == Zookeeper overview ZooKeeper is a centralized service for maintaining configuration information, naming, @@ -82,7 +308,7 @@ Doing so brings in the required Spring Cloud Maven repositories and Build. == Building -:jdkversion: 1.7 +:jdkversion: 1.8 === Basic Compile and Test diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc index 5af314a6..643f94fa 100644 --- a/docs/src/main/asciidoc/README.adoc +++ b/docs/src/main/asciidoc/README.adoc @@ -4,6 +4,10 @@ include::intro.adoc[] include::_attributes.adoc[] +== Quick Start + +include::quickstart.adoc[] + == Zookeeper overview ZooKeeper is a centralized service for maintaining configuration information, naming, diff --git a/docs/src/main/asciidoc/quickstart.adoc b/docs/src/main/asciidoc/quickstart.adoc new file mode 100644 index 00000000..681dc294 --- /dev/null +++ b/docs/src/main/asciidoc/quickstart.adoc @@ -0,0 +1,223 @@ +This quick start walks through using Spring Cloud Zookeeper for Service Discovery and Distributed Configuration. + +First, run Zookeeper on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Zookeeper. + +=== Discovery Client Usage + +To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-discovery`. +The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-discovery`. +We recommend using dependency management and `spring-boot-starter-parent`. +The following example shows a typical Maven configuration: + +[source,xml,indent=0] +.pom.xml +---- + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + + + org.springframework.cloud + spring-cloud-starter-zookeeper-discovery + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + org.springframework.cloud + spring-cloud-dependencies + ${spring-cloud.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +---- + +The following example shows a typical Gradle setup: + +[source,groovy,indent=0] +.build.gradle +---- +plugins { + id 'org.springframework.boot' version ${spring-boot-version} + id 'io.spring.dependency-management' version ${spring-dependency-management-version} + id 'java' +} + +repositories { + mavenCentral() +} + +dependencies { + implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-discovery' + testImplementation 'org.springframework.boot:spring-boot-starter-test' +} +dependencyManagement { + imports { + mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}" + } +} +---- + +Now you can create a standard Spring Boot application, such as the following HTTP server: + +---- +@SpringBootApplication +@RestController +public class Application { + + @GetMapping("/") + public String home() { + return "Hello World!"; + } + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + +} +---- + +When this HTTP server runs, it connects to Zookeeper, which runs on the default local port (2181). +To modify the startup behavior, you can change the location of Zookeeper by using `application.properties`, as shown in the following example: + +---- +spring: + cloud: + zookeeper: + connect-string: localhost:2181 +---- + +You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate`, or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Zookeeper, as shown in the following example: + +[source,java,indent=0] +---- +@Autowired +private DiscoveryClient discoveryClient; + +public String serviceUrl() { + List list = discoveryClient.getInstances("STORES"); + if (list != null && list.size() > 0 ) { + return list.get(0).getUri().toString(); + } + return null; +} +---- + +=== Distributed Configuration Usage + +To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-config`. +The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-config`. +We recommend using dependency management and `spring-boot-starter-parent`. +The following example shows a typical Maven configuration: + +[source,xml,indent=0] +.pom.xml +---- + + + org.springframework.boot + spring-boot-starter-parent + {spring-boot-version} + + + + + + org.springframework.cloud + spring-cloud-starter-zookeeper-config + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + org.springframework.cloud + spring-cloud-dependencies + ${spring-cloud.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +---- + +The following example shows a typical Gradle setup: + +[source,groovy,indent=0] +.build.gradle +---- +plugins { + id 'org.springframework.boot' version ${spring-boot-version} + id 'io.spring.dependency-management' version ${spring-dependency-management-version} + id 'java' +} + +repositories { + mavenCentral() +} + +dependencies { + implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-config' + testImplementation 'org.springframework.boot:spring-boot-starter-test' +} +dependencyManagement { + imports { + mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}" + } +} +---- + +Now you can create a standard Spring Boot application, such as the following HTTP server: + +---- +@SpringBootApplication +@RestController +public class Application { + + @GetMapping("/") + public String home() { + return "Hello World!"; + } + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + +} +---- + +The application retrieves configuration data from Zookeeper. \ No newline at end of file diff --git a/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc b/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc index 82defdd3..a7751679 100644 --- a/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc +++ b/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc @@ -5,6 +5,10 @@ include::intro.adoc[] include::_attributes.adoc[] +== Quick Start + +include::quickstart.adoc[] + [[spring-cloud-zookeeper-install]] == Install Zookeeper See the https://zookeeper.apache.org/doc/current/zookeeperStarted.html[installation