From 6b10f4bdd1ca1ac97b03cb0ea5f2fc9eea0be00e Mon Sep 17 00:00:00 2001 From: Ovidijus Okinskas Date: Mon, 4 Jun 2018 20:36:10 +0100 Subject: [PATCH] Adding appropriate comments on classes and full description in App.java. Removing added function in ServiceAmbassador as it's not appropriate for the example. --- .../java/com/iluwatar/ambassador/App.java | 43 +++++++++++++++++-- .../java/com/iluwatar/ambassador/Client.java | 8 ++-- .../iluwatar/ambassador/RemoteService.java | 9 ++++ .../ambassador/RemoteServiceInterface.java | 3 ++ .../ambassador/ServiceAmbassador.java | 11 +++-- 5 files changed, 61 insertions(+), 13 deletions(-) diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/App.java b/ambassador/src/main/java/com/iluwatar/ambassador/App.java index 0293c1004..32c5f0f1c 100644 --- a/ambassador/src/main/java/com/iluwatar/ambassador/App.java +++ b/ambassador/src/main/java/com/iluwatar/ambassador/App.java @@ -1,5 +1,44 @@ +/** + * The MIT License + * Copyright (c) 2014-2016 Ilkka Seppälä + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ package com.iluwatar.ambassador; +/** + * + * The ambassador pattern creates a helper service that sends network requests on behalf of a + * client. It is often used in cloud-based applications to offload features of a remote service. + * + * An ambassador service can be thought of as an out-of-process proxy that is co-located with + * the client. Similar to the proxy design pattern, the ambassador service provides an interface + * for another remote service. In addition to the interface, the ambassador provides extra + * functionality and features, specifically offloaded common connectivity tasks. This usually + * consists of monitoring, logging, routing, security etc. This is extremely useful in + * legacy applications where the codebase is difficult to modify and allows for improvements + * in the application's networking capabilities. + * + * In this example, we will the ({@link ServiceAmbassador}) class represents the ambassador while the + * ({@link RemoteService}) class represents a remote application. + * + */ public class App { /** @@ -9,11 +48,7 @@ public class App { Client host1 = new Client(); Client host2 = new Client(); - host1.useService(12); host2.useService(73); - - host1.useNewService(12); - host2.useNewService(73); } } diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/Client.java b/ambassador/src/main/java/com/iluwatar/ambassador/Client.java index 0c7bb0394..30bd834e6 100644 --- a/ambassador/src/main/java/com/iluwatar/ambassador/Client.java +++ b/ambassador/src/main/java/com/iluwatar/ambassador/Client.java @@ -22,6 +22,9 @@ */ package com.iluwatar.ambassador; +/** + * A simple Client + */ public class Client { private ServiceAmbassador serviceAmbassador; @@ -34,9 +37,4 @@ public class Client { long result = serviceAmbassador.doRemoteFunction(value); System.out.println(result); } - - void useNewService(int value) { - long result = serviceAmbassador.doAddedFunction(value); - System.out.println(result); - } } diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java index 0c608c151..668e776ce 100644 --- a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java +++ b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java @@ -24,6 +24,9 @@ package com.iluwatar.ambassador; import static java.lang.Thread.sleep; +/** + * A remote legacy application represented by a Singleton implementation. + */ public class RemoteService implements RemoteServiceInterface { private static RemoteService service = null; @@ -39,6 +42,12 @@ public class RemoteService implements RemoteServiceInterface { } + /** + * Remote function takes a value and multiplies it by 10 taking a random amount of time. + * Will sometimes return -1. This immitates connectivity issues a client might have to account for. + * @param value integer value to be multiplied. + * @return if waitTime is more than 200ms, it returns value * 10, otherwise -1. + */ @Override public long doRemoteFunction(int value) { diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java index 50a097316..9f1112da9 100644 --- a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java +++ b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java @@ -22,6 +22,9 @@ */ package com.iluwatar.ambassador; +/** + * Interface shared by ({@link RemoteService}) and ({@link ServiceAmbassador}). + */ interface RemoteServiceInterface { long doRemoteFunction(int value) throws Exception; diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java b/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java index 1c9a2325f..77c7197ff 100644 --- a/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java +++ b/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java @@ -27,6 +27,13 @@ import org.slf4j.LoggerFactory; import static java.lang.Thread.sleep; +/** + * + * ServiceAmbassador provides an interface for a ({@link Client}) to access ({@link RemoteService}). + * The interface adds logging, latency testing and usage of the service in a safe way that will not + * add stress to the remote service when connectivity issues occur. + * + */ public class ServiceAmbassador implements RemoteServiceInterface { private static final Logger LOGGER = LoggerFactory.getLogger(ServiceAmbassador.class); @@ -43,10 +50,6 @@ public class ServiceAmbassador implements RemoteServiceInterface { return safeCall(value); } - long doAddedFunction(int value) { - return safeCall(value) * 5; - } - private long checkLatency(int value) { RemoteService service = RemoteService.getRemoteService(); long startTime = System.currentTimeMillis();