From 6e886921f3c624e09beef74e6929caa102ca58a0 Mon Sep 17 00:00:00 2001 From: evelinec Date: Thu, 16 Jan 2020 09:59:55 -0500 Subject: [PATCH 1/2] Addressed review feedback --- README.adoc | 76 ++++++++++--------- .../faulttolerance/FaultToleranceIT.java | 4 +- 2 files changed, 42 insertions(+), 38 deletions(-) diff --git a/README.adoc b/README.adoc index cd9414ab..3138f31b 100644 --- a/README.adoc +++ b/README.adoc @@ -43,13 +43,14 @@ retry policies, bulkheads, and circuit breakers are popular concepts in this are They dictate whether and when executions take place, and fallbacks offer an alternative result when an execution does not complete successfully. -The application that you will be working with is an `inventory` service, which collects, +The microservice that you will be working with is an `inventory` service, which collects, stores, and returns the system properties. It uses the `system` service to retrieve the system properties for a particular host. You will add fault tolerance to the `inventory` service so that it reacts accordingly when the `system` service is unavailable. -You will use the `@Fallback` annotations from the MicroProfile Fault Tolerance +You will build the fault-tolerance microservice with the `@Fallback` annotation +from the MP Fault Tolerance MicroProfile Fault Tolerance specification to define criteria for when to provide an alternative solution for a failed execution. @@ -81,7 +82,7 @@ mvn liberty:run ``` Point your browser to the http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL, which accesses the -`inventory` service with a localhost hostname. You see the system properties for this host. +`inventory` service with a `localhost` hostname. You see the system properties for this host. When you visit this URL, some of these system properties, such as the OS name and user name, are automatically stored in the inventory. @@ -104,7 +105,7 @@ You do not need to restart the server. Next, return to your browser and point back to the http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL. The fallback mechanism is triggered because the `system` service is now in maintenance. -You see the cached properties for this localhost. +You see the cached properties that were previously stored in the inventory. When you are done checking out the application, go to the [hotspot]`CustomConfigSource.json` file again. @@ -150,32 +151,28 @@ which turns on MicroProfile Fault Tolerance capabilities in Open Liberty. To easily work through this guide, the two provided microservices are set up to run on the same server. To simulate the availability of the services and then to enable fault tolerance, -dynamic configuration with MicroProfile Configuration is used so that you can easily take one service -or the other down for maintenance. If you want to learn more about setting up dynamic configuration, +dynamic configuration with MicroProfile Configuration is used so that you can easily take one service down. +If you want to learn more about setting up dynamic configuration, see https://openliberty.io/guides/microprofile-config.html[Configuring microservices^]. -The following two steps set up the dynamic configuration on the `system` service and its client. -You can move on to the next section, which adds the fallback mechanism on the `inventory` service. - -First, the [hotspot file=0]`src/main/java/io/openliberty/guides/system/SystemResource.java` file has -the [hotspot=21-22 file=0]`isInMaintenance()` condition, which determines that the system properties are returned only if you -set the [hotspot=2 file=1]`io_openliberty_guides_system_inMaintenance` configuration property -to `false` in the [hotspot file=1]`CustomConfigSource` file. -Otherwise, the service returns a [hotspot=24 file=0]`Status.SERVICE_UNAVAILABLE` message, which makes it unavailable. - -Next, the [hotspot file=2]`src/main/java/io/openliberty/guides/inventory/client/SystemClient.java` file -makes a request to the `system` service through the MicroProfile Rest Client API. -If you want to learn more about MicroProfile Rest Client, -you can follow the https://openliberty.io/guides/microprofile-rest-client.html[Consuming RESTful services with template interfaces^] guide. -The `system` service as described in the [hotspot file=0]`SystemResource.java` file -may return a [hotspot=24 file=0]`Status.SERVICE_UNAVAILABLE` message, which is a 503 status code. +First, you set up the dynamic configuration on the `system` service to simulate its availability. +The [hotspot file=0]`SystemResource` class has an injected `SystemConfig` instance, +where the `isInMaintenance()` condition gets the configuration property from the `io_openliberty_guides_system_inMaintenance` key. +- If the configuration property is set to `false`, the `system` service is available and the system properties are returned. +- If the configuration property is set to `true`, the `system` service is unavailable. +The [hotspot=24 file=0]`Status.SERVICE_UNAVAILABLE` message, which is a `503` HTTP response status code. This code indicates that the server being called is unable to handle the request because of a temporary overload or scheduled maintenance, which would -likely be alleviated after some delay. To simulate that the system is unavailable, an [hotspot=22 file=2]`IOException` is thrown. +likely be alleviated after some delay. -The `InventoryManager` class calls the [hotspot=21-23 file=2]`getProperties()` method +Next, you enable the [hotspot file=2]`SystemClient` class to throw an [hotspot=22 file=2]`IOException` +when the `system` service is called and the service is unavailable. +The [hotspot file=2]`SystemClient` class is constructed using MicroProfile Rest Client. +You can follow the https://openliberty.io/guides/microprofile-rest-client.html[Consuming RESTful services with template interfaces^] guide. + +Finally, the `get()` method in the [hotspot file=5]`InventoryManager` class calls the [hotspot=21-23 file=2]`getProperties()` method in the [hotspot file=2]`SystemClient.java` class. -You will look into the `InventoryManager` class in more detail in the next section. +An `IOException` is thrown to simulate that the `system` service is unavailable. SystemResource.java [source, java, linenums, role='code_column'] @@ -207,6 +204,12 @@ pom.xml include::finish/pom.xml[] ---- +InventoryManager.java +[source, java, linenums, role='code_column'] +---- +include::finish/src/main/java/io/openliberty/guides/inventory/InventoryManager.java[] +---- + // ================================================================================================= // Adding the @Fallback annotation // ================================================================================================= @@ -215,7 +218,7 @@ include::finish/pom.xml[] The `inventory` service is now able to recognize that the `system` service was taken down for maintenance. -An IOException is thrown to simulate the `system` service is unavailable. +An `IOException` is thrown to simulate that the `system` service is unavailable. Now, set a fallback method to deal with this failure. @@ -267,15 +270,17 @@ You can learn more about MicroProfile Metrics in the https://openliberty.io/guid The Open Liberty server started in development mode at the beginning of the guide and all the changes were automatically picked up. -When the server is running, point your browser to the -http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL. -You receive the system properties of your local JVM from the `inventory` service. Next, point your +When the server is running, point your browser to the `system` service URL, which is located at http://localhost:9080/system/properties[http://localhost:9080/system/properties^], -to retrieve the system properties for the specific localhost. +to retrieve the system properties for the specific `localhost`. +Next, point your browser to the +http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL. +You see all of the system properties in your local JVM. Notice that the results from the two URLs are identical because the `inventory` service gets its results from calling the `system` service. +When you visit the `http://localhost:9080/inventory/systems/localhost` URL, the OS name and user name properties are stored in the inventory. -To see the application metrics, go to the https://localhost:9443/metrics/application[https://localhost:9443/metrics/application^] URL. Log in as the `admin` user, and use `adminpwd` as the password. +You can also see the application metrics in the https://localhost:9443/metrics/application[https://localhost:9443/metrics/application^] URL. Log in as the `admin` user, and use `adminpwd` as the password. See the following sample outputs for the `@Fallback` annotated method and the fallback method before a fallback occurs: [role="no_copy"] @@ -288,7 +293,7 @@ application:ft_io_openliberty_guides_inventory_inventory_manager_get_invocations application:ft_io_openliberty_guides_inventory_inventory_manager_get_fallback_calls_total 0 ---- -You can test the fault tolerance mechanism of your microservices by dynamically changing +Next, you can test the fault tolerance mechanism of your microservices by dynamically changing the [hotspot=2 file=0]`io_openliberty_guides_system_inMaintenance` property value to `true` in the [hotspot file=0]`resources/CustomConfigSource.json` file, which turns the `system` service in maintenance. @@ -314,16 +319,15 @@ include::finish/src/main/java/io/openliberty/guides/inventory/InventoryManager.j ---- After saving the file, go back to your browser and -refresh to the http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL to view the cached version of -the properties. The [hotspot=23-31 file=1]`fallbackForGet()` method, which is the designated fallback method, is called -when the `system` service is not available. +refresh the http://localhost:9080/inventory/systems/localhost[http://localhost:9080/inventory/systems/localhost^] URL to view the cached values of +the system properties. The [hotspot=23-31 file=1]`fallbackForGet()` method, which is the designated fallback method, is called when the `system` service is not available. The cached system properties contain only the OS name and user name key and value pairs. To see that the `system` service is down, point your browser to the http://localhost:9080/system/properties[http://localhost:9080/system/properties^] URL again. You see that the service displays a 503 HTTP response code. Go to the https://localhost:9443/metrics/application[https://localhost:9443/metrics/application^] URL again. -See the following sample outputs for the `@Fallback` annotated method and the fallback method after a fallback occurs: +See the following metrics outputs for the `@Fallback` annotated method and the fallback method after a fallback occurs: [role="no_copy"] ---- @@ -412,7 +416,7 @@ Results : Tests run: 5, Failures: 0, Errors: 0, Skipped: 0 ---- -To see if the tests detect a failure, comment out the [hotspot=40-41 hotspot=51-52]`changeSystemProperty()` methods +To see if the tests detect a failure, delete the [hotspot=40-41 hotspot=51-52]`changeSystemProperty()` invocations in the [hotspot]`FaultToleranceIT.java` file. Rerun the tests to see that a test failure occurs for the [hotspot=34-54]`testFallbackForGet()` test case. When you are done checking out the service, exit development mode by typing `q` in the shell session diff --git a/finish/src/test/java/it/io/openliberty/guides/faulttolerance/FaultToleranceIT.java b/finish/src/test/java/it/io/openliberty/guides/faulttolerance/FaultToleranceIT.java index f4a0f74b..e2d12fbc 100644 --- a/finish/src/test/java/it/io/openliberty/guides/faulttolerance/FaultToleranceIT.java +++ b/finish/src/test/java/it/io/openliberty/guides/faulttolerance/FaultToleranceIT.java @@ -70,9 +70,9 @@ public void testFallbackForGet() throws InterruptedException { assertResponse(TestUtils.baseUrl, response); obj = response.readEntity(JsonObject.class); int propertiesSizeFallBack = obj.size(); - assertTrue(propertiesSize > propertiesSizeFallBack, + assertTrue(propertiesSize > propertiesSizeFallBack, "The total number of properties from the @Fallback method " - + "is not smaller than the number from the system service, as expected."); + + "should be smaller than the number from the system service."); TestUtils.changeSystemProperty(TestUtils.SYSTEM_MAINTENANCE_TRUE, TestUtils.SYSTEM_MAINTENANCE_FALSE); Thread.sleep(3000); From 584518816b0de21e47d65371bdf5a73c7e0e96c0 Mon Sep 17 00:00:00 2001 From: evelinec Date: Thu, 16 Jan 2020 14:28:33 -0500 Subject: [PATCH 2/2] Proposed 2 options --- README.adoc | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/README.adoc b/README.adoc index 3138f31b..62ae2392 100644 --- a/README.adoc +++ b/README.adoc @@ -149,6 +149,21 @@ This dependency provides a library that allows you to use fault tolerance polici You can also find the [hotspot=mpFaultTolerance file=3]`mpFaultTolerance` feature in your [hotspot file=3]`src/main/liberty/config/server.xml` server configuration, which turns on MicroProfile Fault Tolerance capabilities in Open Liberty. + +Option 1: + +To easily work through this guide, the two provided microservices are set up to run +on the same server. To simulate the availability of the services and then to enable fault tolerance, +dynamic configuration with MicroProfile Configuration is used so that you can easily take one service down. +If you want to learn more about setting up dynamic configuration, +see https://openliberty.io/guides/microprofile-config.html[Configuring microservices^]. + +The the `system` service reads the `io_openliberty_guides_system_inMaintenance` custom configuration property, which is set to `true` or `false` to determine +the `system` service's availability. An `IOException` is thrown to simulate that the `system` service is unavailable. + + +Option 2: + To easily work through this guide, the two provided microservices are set up to run on the same server. To simulate the availability of the services and then to enable fault tolerance, dynamic configuration with MicroProfile Configuration is used so that you can easily take one service down. @@ -157,20 +172,23 @@ see https://openliberty.io/guides/microprofile-config.html[Configuring microserv First, you set up the dynamic configuration on the `system` service to simulate its availability. The [hotspot file=0]`SystemResource` class has an injected `SystemConfig` instance, -where the `isInMaintenance()` condition gets the configuration property from the `io_openliberty_guides_system_inMaintenance` key. +where the `isInMaintenance()` condition gets the value from the `io_openliberty_guides_system_inMaintenance` configuration property. + - If the configuration property is set to `false`, the `system` service is available and the system properties are returned. - If the configuration property is set to `true`, the `system` service is unavailable. + The [hotspot=24 file=0]`Status.SERVICE_UNAVAILABLE` message, which is a `503` HTTP response status code. This code indicates that the server being called is unable to handle the request because of a temporary overload or scheduled maintenance, which would likely be alleviated after some delay. -Next, you enable the [hotspot file=2]`SystemClient` class to throw an [hotspot=22 file=2]`IOException` +Next, the [hotspot file=2]`SystemClient` class throws an [hotspot=22 file=2]`IOException` when the `system` service is called and the service is unavailable. The [hotspot file=2]`SystemClient` class is constructed using MicroProfile Rest Client. You can follow the https://openliberty.io/guides/microprofile-rest-client.html[Consuming RESTful services with template interfaces^] guide. -Finally, the `get()` method in the [hotspot file=5]`InventoryManager` class calls the [hotspot=21-23 file=2]`getProperties()` method +Finally, the `inventory` service calls the `system` service to get the system properties. +The `get()` method in the [hotspot file=5]`InventoryManager` class calls the [hotspot=21-23 file=2]`getProperties()` method in the [hotspot file=2]`SystemClient.java` class. An `IOException` is thrown to simulate that the `system` service is unavailable.