diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2b8a9a17b8..6b773f3046 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,261 +1,41 @@ -# Development Workflow +# Development Setup + +You need Java 11 or higher to run the build. The build produces Java 8-compatible +bytecode. + +Install [`bazelisk`](https://github.com/bazelbuild/bazelisk) in your `PATH` +for gapic-generator-java's Bazel build. ## Set Up 1. Clone this repo. 2. (OPTIONAL) Copy the Git pre-commit hooks. This will automatically check the build, run - tests, and perform linting before each commit. (Symlinks don't seem to work, - but if you find a way, please add it here!) + tests, and perform linting before each commit. (Symlinks don't seem to work, + but if you find a way, please add it here!) ```sh cp .githooks/pre-commit .git/hooks/pre-commit ``` - -3. Install [`bazelisk`](https://github.com/bazelbuild/bazelisk) in your `PATH`. - -## Code Formatting - -- Run linter checks without actually doing the formatting. - ```sh - mvn fmt:check - ``` +## Run Tests for All Modules -- Format files. - - ```sh - mvn fmt:format - ``` - -## Test Running - -- Run all unit and integration tests. - - ```sh - mvn install # unit tests, maven test wouldn't work in root folder because gapic-generator-java is dependant on test jars of gax-java - bazel test //... # integration tests - ``` - -- Run all unit tests. +- Run all unit tests in all modules. ```sh mvn install ``` -- For running unit tests in `gapic-generator-java` submodule, first build all modules with `mvn install -DskipTests`, then `cd` into `gapic-generator-java` submodule for the following commands: - - Run a single or multiple unit tests: - - ```sh - mvn test -Dtest=JavaCodeGeneratorTest - - mvn test "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]" - ``` - - - Update all unit test golden files: - - ```sh - mvn test -DupdateUnitGoldens - ``` - - Update a single unit test golden file, for example `JavaCodeGeneratorTest.java`: - - ```sh - mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest - ``` +## Code Formatting -- Run a single integration test for API like `Redis`, it generates Java source - code using the Java microgenerator and compares them with the goldens files - in `test/integration/goldens/redis`. +- Run linter checks without actually doing the formatting. ```sh - bazel test //test/integration:redis + mvn fmt:check ``` -- Update integration test golden files, for example `Redis`. This clobbers all the - files in `test/integration/goldens/redis`. +- Format files. ```sh - bazel run //test/integration:update_redis + mvn fmt:format ``` - -## Showcase Integration Testing - -[GAPIC Showcase](https://github.com/googleapis/gapic-showcase) is an API that demonstrates Generated -API Client (GAPIC) features and common API patterns used by Google. It follows the [Cloud APIs -design guide](https://cloud.google.com/apis/design/). `gapic-generator-java` generates a client for -the Showcase API which can communicate with a local Showcase server to perform integration tests. - -### Requirements - -* Install [Go](https://go.dev) in your `PATH`. - -### Installing the Server - -Using the latest version of showcase is recommended, but backward compatibility between server -versions is not guaranteed. If changing the version of the server, it may also be necessary to -update to a compatible client version in `./WORKSPACE`. - -```shell -$ GAPIC_SHOWCASE_VERSION=0.25.0 -$ go install github.com/googleapis/gapic-showcase/cmd/gapic-showcase@v"$GAPIC_SHOWCASE_VERSION" -$ PATH=$PATH:`go env GOPATH`/bin -$ gapic-showcase --help -> Root command of gapic-showcase -> -> Usage: -> gapic-showcase [command] -> -> Available Commands: -> completion Emits bash a completion for gapic-showcase -> compliance This service is used to test that GAPICs... -> echo This service is used showcase the four main types... -> help Help about any command -> identity A simple identity service. -> messaging A simple messaging service that implements chat... -> run Runs the showcase server -> sequence Sub-command for Service: Sequence -> testing A service to facilitate running discrete sets of... -> -> Flags: -> -h, --help help for gapic-showcase -> -j, --json Print JSON output -> -v, --verbose Print verbose output -> --version version for gapic-showcase -``` - -### Running the Server - -Run the showcase server to allow requests to be sent to it. This opens port `:7469` to send and -receive requests. - -```shell -$ gapic-showcase run -> 2022/11/21 16:22:15 Showcase listening on port: :7469 -> 2022/11/21 16:22:15 Starting endpoint 0: gRPC endpoint -> 2022/11/21 16:22:15 Starting endpoint 1: HTTP/REST endpoint -> 2022/11/21 16:22:15 Starting endpoint multiplexer -> 2022/11/21 16:22:15 Listening for gRPC-fallback connections -> 2022/11/21 16:22:15 Listening for gRPC connections -> 2022/11/21 16:22:15 Listening for REST connections -> 2022/11/21 16:22:15 Fallback server listening on port: :1337 -``` - -### Running the Integration Tests - -Open a new terminal window in the root project directory. - -```shell -$ cd showcase -$ mvn verify -P enable-integration-tests -P enable-golden-tests -``` - -Note: - -* `-P enable-golden-tests` is optional. These tests do not require a local server. - -### Update the Golden Showcase Files - -Open a new terminal window in the root project directory. - -```shell -$ cd showcase -$ mvn compile -P update -``` - -## Running the Plugin under googleapis with local gapic-generator-java - -For running the Plugin with showcase protos and local gapic-generator-java, see above section "Showcase Integration Testing". - -To generate a production GAPIC API: - -1. Clone [googleapis](https://github.com/googleapis/googleapis). - -2. Modify `googleapis/WORKSPACE` to point to local gapic-generator-java - - Normally, googleapis's build pulls in gapic-generator-java from Maven Central. - For a local run, we first need to build a local SNAPSHOT jar of the generator. Then we point googleapis to - both the local SNAPSHOT jar and the local copy of the generator. - - Replace the following section in googleapis - ``` - _gapic_generator_java_version = "2.13.0" - - maven_install( - artifacts = [ - "com.google.api:gapic-generator-java:" + _gapic_generator_java_version, - ], - #Update this False for local development - fail_on_missing_checksum = True, - repositories = [ - "m2Local", - "https://repo.maven.apache.org/maven2/", - ] - ) - - http_archive( - name = "gapic_generator_java", - strip_prefix = "gapic-generator-java-%s" % _gapic_generator_java_version, - urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version], - ) - ``` - - to - - ``` - _gapic_generator_java_version = "2.13.1-SNAPSHOT" - - maven_install( - artifacts = [ - "com.google.api:gapic-generator-java:" + _gapic_generator_java_version, - ], - #Update this False for local development - fail_on_missing_checksum = False, - repositories = [ - "m2Local", - "https://repo.maven.apache.org/maven2/", - ] - ) - - local_repository( - name = "gapic_generator_java", - path = "/absolute/path/to/your/local/gapic-generator-java", - ) - ``` - - Note: At the time of writing, the gapic-generator version was `2.13.0`. Update the version to the latest version in the pom.xml - -3. Build the new target. - - You can generate any client library based on the protos within googleapis. - You just need the name of the service within the `java_gapic_assembly_gradle_pkg` - rules within the service's `BUILD.bazel` file. - For instance, to run your local generator on the `speech`'s v2 service, you can - run: - - ``` - bazel build //google/cloud/speech/v2:google-cloud-speech-v2-java - ``` - - Note: If you are running into bazel build issues, you can try to remove gapic-generator-java cached in your local m2 - Try running this command: - ``` - rm -rf ~/.m2/repository/com/google/api/ - ``` - and then rebuild gapic-generator-java (`mvn clean install`). - -## FAQ - -### Error in workspace: workspace() got unexpected keyword argument 'managed_directories' - -Full Error: - -``` -ERROR: Traceback (most recent call last): - File "/home/alicejli/googleapis/WORKSPACE", line 1, column 10, in - workspace( -Error in workspace: workspace() got unexpected keyword argument 'managed_directories' -ERROR: Error computing the main repository mapping: Encountered error while reading extension file 'tools/build_defs/repo/http.bzl': no such package '@bazel_tools//tools/build_defs/repo': error loading package 'external': Could not load //external package -``` - -You may be using the latest version of bazel which this project does not support yet. Try installing bazelisk to force -bazel to use the version specified in `.bazeliskrc` diff --git a/README.md b/README.md index 21b323f741..8fe2ae2e6c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,22 @@ [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=googleapis_gapic-generator-java&metric=coverage)](https://sonarcloud.io/summary/new_code?id=googleapis_gapic-generator-java) -# API Client Generator for Java -Generates a Java client library from protocol buffers. -Replaces the Java parts of the -[older monolithic generator](https://github.com/googleapis/gapic-generator). +This repository consists of the following modules: + +- **[gapic-generator-java](./gapic-generator-java/README.md)**: the Protobuf compiler plugin to generate Java code. + See [gapic-generator-java/DEVELOPMENT.md] for setup. +- **[gax-java](./gax-java/README.md)**: the runtime library required for Google Cloud client libraries, + including the ones generated by gapic-generator-java. +- **[java-common-protos](./java-common-protos/README.md)** and **[api-common-java](./api-common-java/README.md)**: Protobuf-generated common + classes for Google services. (They are not generated by gapic-generator-java) +- **[java-iam](./java-iam/README.md)**: Protobuf-generated classes for Google's + Identity and Access + Management (IAM). (They are not generated by gapic-generator-java) +- **[showcase](./showcase/README.md)**: demonstration of the generated client + library for the fake "Showcase" API. +- **[gapic-generator-java-bom](./gapic-generator-java-bom)**: The Bill-of-Material for the libraries + produced from this repository. This is used by [google-cloud-java/java-shared-dependencies]( + https://github.com/googleapis/google-cloud-java/blob/main/java-shared-dependencies/first-party-dependencies/pom.xml). + +## Development Setup + +See [DEVELOPMENT.md](DEVELOPMENT.md). \ No newline at end of file diff --git a/gapic-generator-java/DEVELOPMENT.md b/gapic-generator-java/DEVELOPMENT.md index 5eb2740fa0..acdc71df66 100644 --- a/gapic-generator-java/DEVELOPMENT.md +++ b/gapic-generator-java/DEVELOPMENT.md @@ -1,210 +1,174 @@ # Development Workflow -## Set Up - -1. Clone this repo. +## Test Running -2. Copy the Git pre-commit hooks. This will automatically check the build, run - tests, and perform linting before each commit. (Symlinks don't seem to work, - but if you find a way, please add it here!) +### Unit Tests - ```sh - cp .githooks/pre-commit .git/hooks/pre-commit - ``` +To run the unit tests in `gapic-generator-java` submodule, first build all +modules with `mvn -pl '!gapic-generator-java' install -DskipTests` at the root +directory, +then `cd` into `gapic-generator-java` submodule for the following commands: -## Code Formatting +- Run all unit tests: -- Run linter checks without actually doing the formatting. + ```sh + # In gapic-generator-java submodule + mvn test + ``` - ```sh - bazel run //:google_java_format_verification - ``` - or - ```sh - mvn fmt:check - ``` +- Run a single or multiple unit tests: -- Format files. + ```sh + # In gapic-generator-java submodule + mvn test -Dtest=JavaCodeGeneratorTest - ```sh - bazel run //:google_java_format - ``` - or - ```sh - mvn fmt:format - ``` + mvn test "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]" + ``` -## Test Running +- Update all unit test golden files: -- Run all unit and integration tests. + ```sh + # In gapic-generator-java submodule + mvn test -DupdateUnitGoldens + ``` - ```sh - bazel test //... - ``` +- Update a single unit test golden file, for example `JavaCodeGeneratorTest.java`: -- Run all unit tests. + ```sh + # In gapic-generator-java submodule + mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest + ``` - ```sh - bazel test //:units - ``` - or - ```sh - mvn test - ``` +Note that `mvn -pl '!gapic-generator-java' install -DskipTests` +at the root directory is needed for `mvn test` commands, +because the gapic-generator-java submodule depends on the "test jars" of +gax-java. The test jars are absent until Maven's "package" phase, which is later +than the "test" phase. -- Run a single unit test like `JavaCodeGeneratorTest.java`: +### Integration Tests - ```sh - bazel test //:unit_com_google_api_generator_engine_JavaCodeGeneratorTest - ``` - or - ```sh - mvn test -Dtest=JavaCodeGeneratorTest +To run integration test for gapic-generator-java, run this Bazel command in the +root of the repository (where you have WORKSPACE file for Bazel.) - mvn test "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]" - ``` - -- Update all unit test golden files: +```sh +# In the repository root directory +bazelisk test //... # integration tests +``` - ```sh - mvn test -DupdateUnitGoldens - ``` -- Update a single unit test golden file, for example `JavaCodeGeneratorTest.java`: +- Run a single integration test for API like `Redis`, it generates Java source + code using the Java microgenerator and compares them with the goldens files + in `test/integration/goldens/redis`. ```sh - bazel run //:update_com_google_api_generator_engine_JavaCodeGeneratorTest - ``` - or - ```sh - mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest + # In the repository root directory + bazelisk test //test/integration:redis ``` -- Run a single integration test for API like `Redis`, it generates Java source - code using the Java microgenerator and compares them with the goldens files - in `test/integration/goldens/redis`. +- Update integration test golden files, for example `Redis`. This clobbers all the + files in `test/integration/goldens/redis`. ```sh - bazel test //test/integration:redis + # In the repository root directory + bazelisk run //test/integration:update_redis ``` -- Update integration test golden files, for example `Redis`. This clobbers all the - files in `test/integration/goldens/redis`. +## Running the Plugin under googleapis with local gapic-generator-java - ```sh - bazel run //test/integration:update_redis - ``` +For running the Plugin with showcase protos and local gapic-generator-java, see +[Showcase Integration Testing](../showcase/README.md). -## Running the Plugin +To generate a production GAPIC API: -1. Clone [googleapis](https://github.com/googleapis/googleapis) and - [gapic-showcase](https://github.com/googleapis/gapic-showcase/). +1. Clone [googleapis](https://github.com/googleapis/googleapis). -2. Copy the protos from Showcase into googleapis/google/showcase. +2. Modify `googleapis/WORKSPACE` to point to local gapic-generator-java - ```sh - mkdir googleapis/google/showcase - cp -r gapic-showcase/schema/google/showcase/v1beta1 googleapis/google/showcase/v1beta1 - ``` + Normally, googleapis's build pulls in gapic-generator-java from Maven Central. + For a local run, we first need to build a local SNAPSHOT jar of the generator. Then we point googleapis to + both the local SNAPSHOT jar and the local copy of the generator. -3. Add the new microgenerator rules to - `googleapis/google/showcase/v1beta1/BUILD.bazel` file as follows: - - ```python - load( - "@com_google_googleapis_imports//:imports.bzl", - # Existing rules here. - "java_gapic_assembly_gradle_pkg", - "java_gapic_library", - "java_proto_library", - "proto_library_with_info", - ) + Replace the following section in googleapis + ``` + _gapic_generator_java_version = "2.13.0" - proto_library_with_info( - name = "showcase_proto_with_info", - deps = [ - ":showcase_proto", + maven_install( + artifacts = [ + "com.google.api:gapic-generator-java:" + _gapic_generator_java_version, ], + #Update this False for local development + fail_on_missing_checksum = True, + repositories = [ + "m2Local", + "https://repo.maven.apache.org/maven2/", + ] ) - - java_proto_library( - name = "showcase_java_proto", - deps = [ - ":showcase_proto", - ], + + http_archive( + name = "gapic_generator_java", + strip_prefix = "gapic-generator-java-%s" % _gapic_generator_java_version, + urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version], ) + ``` - # This should either replace the existing monolith target or have a unique name - # that includes "java_gapic". - java_gapic_library( - name = "showcase_java_gapic", - srcs = [":showcase_proto_with_info"], - grpc_service_config = "showcase_grpc_service_config.json", - test_deps = [ - ":showcase_java_grpc", - ], - deps = [ - ":showcase_java_proto", - ], - ) + to - java_gapic_assembly_gradle_pkg( - # This name should be unique from the existing target name. - name = "google-cloud-showcase-v1beta1-java", - deps = [ - # This is the new microgen target above. - ":showcase_java_gapic", - # The following targets already exist. - ":showcase_java_grpc", - ":showcase_java_proto", - ":showcase_proto", + ``` + _gapic_generator_java_version = "2.13.1-SNAPSHOT" + + maven_install( + artifacts = [ + "com.google.api:gapic-generator-java:" + _gapic_generator_java_version, ], + #Update this False for local development + fail_on_missing_checksum = False, + repositories = [ + "m2Local", + "https://repo.maven.apache.org/maven2/", + ] ) - ``` - -4. Point to local gapic-generator-java - - Normally, googleapis's build pulls in googleapis/gapic-generator-java from the - Internet: - - ``` - # Java microgenerator. - … - _gapic_generator_java_version = "2.1.0" - - http_archive( + + local_repository( name = "gapic_generator_java", - … - urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version], + path = "/absolute/path/to/your/local/gapic-generator-java", ) ``` - By replacing this portion using the built-in local_repository rule, you can mak - it refer to your local development repo: + Note: At the time of writing, the gapic-generator version was `2.13.0`. Update the version to the latest version in the pom.xml - ``` - local_repository( - name = "gapic_generator_java", - path = "/home//gapic-generator-java", - ) - ``` +3. Build the new target. -5. Build the new target. - - ```sh - cd googleapis - bazel build //google/showcase/v1beta1:showcase_java_gapic - ``` - You can generate any client library based on the protos within googleapis. You just need the name of the service within the `java_gapic_assembly_gradle_pkg` rules within the service's `BUILD.bazel` file. For instance, to run your local generator on the `speech`'s v2 service, you can run: - + + ``` + bazelisk build //google/cloud/speech/v2:google-cloud-speech-v2-java + ``` + + Note: If you are running into bazel build issues, you can try to remove gapic-generator-java cached in your local m2 + Try running this command: ``` - bazel build //google/cloud/speech/v2:google-cloud-speech-v2-java + rm -rf ~/.m2/repository/com/google/api/ ``` + and then rebuild gapic-generator-java (`mvn clean install`). + +## FAQ + +### Error in workspace: workspace() got unexpected keyword argument 'managed_directories' + +Full Error: +``` +ERROR: Traceback (most recent call last): + File "/home/alicejli/googleapis/WORKSPACE", line 1, column 10, in + workspace( +Error in workspace: workspace() got unexpected keyword argument 'managed_directories' +ERROR: Error computing the main repository mapping: Encountered error while reading extension file 'tools/build_defs/repo/http.bzl': no such package '@bazel_tools//tools/build_defs/repo': error loading package 'external': Could not load //external package +``` +You may be using the latest version of bazel which this project does not support yet. Try installing bazelisk to force +bazel to use the version specified in `.bazeliskrc` diff --git a/gapic-generator-java/README.md b/gapic-generator-java/README.md index 21b323f741..928ad7b9ff 100644 --- a/gapic-generator-java/README.md +++ b/gapic-generator-java/README.md @@ -4,3 +4,5 @@ Generates a Java client library from protocol buffers. Replaces the Java parts of the [older monolithic generator](https://github.com/googleapis/gapic-generator). + +See [DEVELOPMENT.md](DEVELOPMENT.md) for setting up development environment. diff --git a/gax-java/CONTRIBUTING.md b/gax-java/CONTRIBUTING.md index 110ed02ec0..321735f3fd 100644 --- a/gax-java/CONTRIBUTING.md +++ b/gax-java/CONTRIBUTING.md @@ -20,21 +20,6 @@ frustration later on. All submissions, including submissions by project members, require review. We use Github pull requests for this purpose. -### Building -To build GAX: - -```sh -# Go to the repository root -cd gapic-generator-java - -# Install dependency modules to local Maven repository. Note that -# gapic-generator-java module is not a dependency of gax-java -mvn -B -ntp install -DskipTests --projects '!gapic-generator-java,!gax-java' - -# Build and install gax-java -mvn clean install -f gax-java -``` - ### The small print Contributions made by corporations are covered by a different agreement than the one above, the diff --git a/gax-java/DEVELOPMENT.md b/gax-java/DEVELOPMENT.md new file mode 100644 index 0000000000..8288ce0ad7 --- /dev/null +++ b/gax-java/DEVELOPMENT.md @@ -0,0 +1,23 @@ +# Development of gax-java + +## Building + +To build GAX: + +```sh +# Go to the repository root +cd gapic-generator-java + +# Install dependency modules to local Maven repository. Note that +# gapic-generator-java module is not a dependency of gax-java +mvn -pl '!gapic-generator-java,!gax-java' install -DskipTests + +# Build and install gax-java +mvn clean install -f gax-java +``` + +## How to see the effect of GAX change in code generation by gapic-generator-java + +To see the effect of GAX changes in local gapic-generator-java invocation, see +"Running the Plugin under googleapis with local gapic-generator-java" in +[gapic-generator-java/DEVELOPMENT.md](../gapic-generator-java/DEVELOPMENT.md) diff --git a/gax-java/README.md b/gax-java/README.md index a0d1aa77a3..e3666de1cd 100644 --- a/gax-java/README.md +++ b/gax-java/README.md @@ -1,9 +1,7 @@ Google API Extensions for Java ============================== -[![Build Status](https://travis-ci.org/googleapis/gax-java.svg?branch=main)](https://travis-ci.org/googleapis/gax-java) - -- [Documentation](https://googleapis.dev/java/gax/latest/) +- [API Documentation](https://cloud.google.com/java/docs/reference/gax/latest/overview.html) Google API Extensions for Java (GAX Java) is a library which aids in the development of client libraries for server APIs, based on [GRPC](http://grpc.io) @@ -15,7 +13,7 @@ files can use services such as paged list iteration, request batching, and polling of long-running operations to provide a more convenient and idiomatic API surface to callers. -Currently, this library shouldn't be used independently from google-cloud-java, otherwise there is +Currently, this library shouldn't be used independently of google-cloud-java, otherwise there is a high risk of diamond dependency problems, because google-cloud-java uses beta features from this library which can change in breaking ways between versions. See [VERSIONING](#versioning) for more information. @@ -36,30 +34,32 @@ If you are using Maven, add this to your pom.xml file com.google.api gax - 2.8.1 + 2.23.0 com.google.api gax-grpc - 2.8.1 + 2.23.0 ``` If you are using Gradle, add this to your dependencies ```Groovy -compile 'com.google.api:gax:2.8.1', - 'com.google.api:gax-grpc:2.8.1' +compile 'com.google.api:gax:2.23.0', + 'com.google.api:gax-grpc:2.23.0' ``` If you are using SBT, add this to your dependencies ```Scala -libraryDependencies += "com.google.api" % "gax" % "2.8.1" -libraryDependencies += "com.google.api" % "gax-grpc" % "2.8.1" +libraryDependencies += "com.google.api" % "gax" % "2.23.0" +libraryDependencies += "com.google.api" % "gax-grpc" % "2.23.0" ``` [//]: # ({x-version-update-end}) +To find the latest version, see https://search.maven.org/artifact/com.google.api/gax. + Java Versions ------------- diff --git a/showcase/README.md b/showcase/README.md new file mode 100644 index 0000000000..4f2604469f --- /dev/null +++ b/showcase/README.md @@ -0,0 +1,83 @@ +# Showcase Integration Testing + +[GAPIC Showcase](https://github.com/googleapis/gapic-showcase) is an API that demonstrates Generated +API Client (GAPIC) features and common API patterns used by Google. It follows the [Cloud APIs +design guide](https://cloud.google.com/apis/design/). `gapic-generator-java` generates a client for +the Showcase API which can communicate with a local Showcase server to perform integration tests. + +## Requirements + +* Install [Go](https://go.dev) in your `PATH`. + +## Installing the Server + +Using the latest version of showcase is recommended, but backward compatibility between server +versions is not guaranteed. If changing the version of the server, it may also be necessary to +update to a compatible client version in `./WORKSPACE`. + +```shell +$ GAPIC_SHOWCASE_VERSION=0.25.0 +$ go install github.com/googleapis/gapic-showcase/cmd/gapic-showcase@v"$GAPIC_SHOWCASE_VERSION" +$ PATH=$PATH:`go env GOPATH`/bin +$ gapic-showcase --help +> Root command of gapic-showcase +> +> Usage: +> gapic-showcase [command] +> +> Available Commands: +> completion Emits bash a completion for gapic-showcase +> compliance This service is used to test that GAPICs... +> echo This service is used showcase the four main types... +> help Help about any command +> identity A simple identity service. +> messaging A simple messaging service that implements chat... +> run Runs the showcase server +> sequence Sub-command for Service: Sequence +> testing A service to facilitate running discrete sets of... +> +> Flags: +> -h, --help help for gapic-showcase +> -j, --json Print JSON output +> -v, --verbose Print verbose output +> --version version for gapic-showcase +``` + +## Running the Server + +Run the showcase server to allow requests to be sent to it. This opens port `:7469` to send and +receive requests. + +```shell +$ gapic-showcase run +> 2022/11/21 16:22:15 Showcase listening on port: :7469 +> 2022/11/21 16:22:15 Starting endpoint 0: gRPC endpoint +> 2022/11/21 16:22:15 Starting endpoint 1: HTTP/REST endpoint +> 2022/11/21 16:22:15 Starting endpoint multiplexer +> 2022/11/21 16:22:15 Listening for gRPC-fallback connections +> 2022/11/21 16:22:15 Listening for gRPC connections +> 2022/11/21 16:22:15 Listening for REST connections +> 2022/11/21 16:22:15 Fallback server listening on port: :1337 +``` + +## Running the Integration Tests + +Open a new terminal window in the root project directory. + +```shell +$ cd showcase +$ mvn verify -P enable-integration-tests -P enable-golden-tests +``` + +Note: + +* `-P enable-golden-tests` is optional. These tests do not require a local server. + +## Update the Golden Showcase Files + +Open a new terminal window in the root project directory. + +```shell +$ cd showcase +$ mvn compile -P update +```