examples: Add XDS client example

.travis.yml

@@ -29,6 +29,7 @@ install:
   - pushd examples/example-hostname && mvn verify && popd
   - pushd examples/example-tls && ../gradlew clean build && popd
   - pushd examples/example-kotlin && ../gradlew build && popd
+  - pushd examples/example-xds && ../gradlew build && popd
 
 before_script:
   - test -z "$(git status --porcelain)" || (git status && echo Error Working directory is not clean. Forget to commit generated files? && false)

RELEASING.md

@@ -51,6 +51,7 @@ $ VERSION_FILES=(
   examples/example-kotlin/android/helloworld/app/build.gradle
   examples/example-tls/build.gradle
   examples/example-tls/pom.xml
+  examples/example-xds/build.gradle
   )
 ```
 

buildscripts/kokoro/unix.sh

@@ -71,6 +71,9 @@ if [[ -z "${SKIP_TESTS:-}" ]]; then
   pushd examples/example-tls
   mvn clean verify --batch-mode
   popd
+  pushd examples/example-xds
+  ../gradlew build $GRADLE_FLAGS
+  popd
   # TODO(zpencer): also build the GAE examples
 fi
 

examples/example-xds/README.md

@@ -0,0 +1,79 @@
+gRPC XDS Example
+================
+
+The XDS example is a Hello World client capable of being configured with the
+XDS management protocol. Out-of-the-box it behaves the same as hello world
+client.
+
+__XDS support is incomplete and experimental, with limited compatibility. It
+will be very hard to produce a working enviornment just by this example. Please
+refer to documentation specific for your XDS management server and
+environment.__
+
+The example requires grpc-xds, but grpc-xds is not currently being published.
+You will thus need to build it yourself. This should guide you, but if you
+encounter issues please consult [COMPILING.md](../../COMPILING.md).
+
+### Build the example
+
+1. The server does not use XDS, so recent releases work fine. Building using
+recent releases is much easier, so check out the most recent release tag:
+```
+$ git checkout v1.27.0
+```
+
+2. Build the hello-world example server or the hostname example server. See
+   [the examples README](../README.md) or the
+   [hostname example README](../example-hostname/README.md).
+
+3. Since XDS is still developing rapidly, XDS-using code should be built from
+master:
+```
+$ git checkout master
+```
+
+4. Building protoc-gen-grpc-java (the protoc plugin) requires a bit of work and
+   isn't necessary. So change the hello-world example to use the last released
+   version of the plugin. In `grpc-java/examples/build.gradle`, change:
+```
+        grpc { artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}" }
+```
+To:
+```
+        grpc { artifact = "io.grpc:protoc-gen-grpc-java:1.27.0" }
+```
+
+
+5. Build this client. From the `grpc-java/examples/examples-xds` directory:
+```
+$ ../gradlew -PskipCodegen=true -PskipAndroid=true --include-build ../.. installDist
+```
+
+This creates the script `build/install/example-xds/bin/xds-hello-world-client`
+that runs the example.
+
+To start the server, run:
+
+```
+$ ../build/install/hostname/bin/hello-world-server
+$ # or
+$ ../example-hostname/build/install/hostname/bin/hostname-server
+```
+
+And in a different terminal window run this client:
+
+```
+$ ./build/install/example-xds/bin/xds-hello-world-client
+```
+
+However, that didn't use XDS! To use XDS we assume you have deployed the server
+in your deployment environment and know its name. You need to set the
+`GRPC_XDS_BOOTSTRAP` environment variable to point to a gRPC XDS bootstrap
+file (see [gRFC A27](https://github.com/grpc/proposal/pull/170) for the
+bootstrap format). Then use the `xds-experimental:` target scheme during
+channel creation.
+
+```
+$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
+$ ./build/install/example-xds/bin/xds-hello-world-client "XDS world" xds-experimental:///yourServersName
+```

examples/example-xds/build.gradle

@@ -0,0 +1,43 @@
+plugins {
+    id 'application' // Provide convenience executables for trying out the examples.
+    id 'java'
+}
+
+repositories {
+    maven { // The google mirror is less flaky than mavenCentral()
+        url "https://maven-central.storage-download.googleapis.com/repos/central/data/" }
+    mavenCentral()
+    mavenLocal()
+}
+
+sourceCompatibility = 1.7
+targetCompatibility = 1.7
+
+// IMPORTANT: You probably want the non-SNAPSHOT version of gRPC. Make sure you
+// are looking at a tagged version of the example and not "master"!
+
+// Feel free to delete the comment at the next line. It is just for safely
+// updating the version in our release process.
+def grpcVersion = '1.28.0-SNAPSHOT' // CURRENT_GRPC_VERSION
+
+dependencies {
+    // This example's client is the same as the helloworld client. We depend on the helloworld
+    // client's code here
+    implementation ':examples'
+    // The only change necessary is an extra runtime dependency on io.grpc:grpc-xds
+    runtimeOnly "io.grpc:grpc-xds:${grpcVersion}"
+}
+
+startScripts.enabled = false
+
+task helloWorldClient(type: CreateStartScripts) {
+    mainClassName = 'io.grpc.examples.helloworld.HelloWorldClient'
+    applicationName = 'xds-hello-world-client'
+    outputDir = new File(project.buildDir, 'tmp')
+    classpath = startScripts.classpath
+}
+
+applicationDistribution.into('bin') {
+    from(helloWorldClient)
+    fileMode = 0755
+}

examples/example-xds/settings.gradle

@@ -0,0 +1,3 @@
+rootProject.name = 'example-xds'
+
+includeBuild '..'