#590 explanation for Ambassador

ambassador/README.md

@@ -10,28 +10,37 @@ tags:
 ---
 
 ## Intent
+
 Provide a helper service instance on a client and offload common functionality away from a shared resource.
 
 ## Explanation
+
 Real world example
 
-> A remote service has many clients accessing a function it provides. The service is a legacy application and is impossible to update. Large numbers of requests from users are causing connectivity issues. New rules for request frequency should be implemented along with latency checks and client-side logging.
+> A remote service has many clients accessing a function it provides. The service is a legacy application and is 
+> impossible to update. Large numbers of requests from users are causing connectivity issues. New rules for request 
+> frequency should be implemented along with latency checks and client-side logging.
 
 In plain words
 
-> Using the ambassador pattern, we can implement less-frequent polling from clients along with latency checks and logging.
+> With the Ambassador pattern, we can implement less-frequent polling from clients along with latency checks and 
+> logging.
 
 Microsoft documentation states
 
-> An ambassador service can be thought of as an out-of-process proxy that is co-located with the client. This pattern can be useful for offloading common client connectivity tasks such as monitoring, logging, routing, security (such as TLS), and resiliency patterns in a language agnostic way. It is often used with legacy applications, or other applications that are difficult to modify, in order to extend their networking capabilities. It can also enable a specialized team to implement those features.
+> An ambassador service can be thought of as an out-of-process proxy which is co-located with the client. This pattern 
+> can be useful for offloading common client connectivity tasks such as monitoring, logging, routing, 
+> security (such as TLS), and resiliency patterns in a language agnostic way. It is often used with legacy applications, 
+> or other applications that are difficult to modify, in order to extend their networking capabilities. It can also 
+> enable a specialized team to implement those features.
 
 **Programmatic Example**
 
-With the above example in mind we will imitate the functionality in a simple manner. We have an interface implemented by the remote service as well as the ambassador service:
+With the above introduction in mind we will imitate the functionality in this example. We have an interface implemented 
+by the remote service as well as the ambassador service:
 
 ```java
 interface RemoteServiceInterface {
-
     long doRemoteFunction(int value) throws Exception;
 }
 ```
@@ -136,7 +145,7 @@ public class Client {
 }
 ```
 
-And here are two clients using the service.
+Here are two clients using the service.
 
 ```java
 public class App {
@@ -149,13 +158,29 @@ public class App {
 }
 ```
 
+Here's the output for running the example:
+
+```java
+Time taken (ms): 111
+Service result: 120
+Time taken (ms): 931
+Failed to reach remote: (1)
+Time taken (ms): 665
+Failed to reach remote: (2)
+Time taken (ms): 538
+Failed to reach remote: (3)
+Service result: -1
+```
+
 ## Class diagram
+
 ![alt text](./etc/ambassador.urm.png "Ambassador class diagram")
 
 ## Applicability
-Ambassador is applicable when working with a legacy remote service that cannot
-be modified or would be extremely difficult to modify. Connectivity features can
-be implemented on the client avoiding the need for changes on the remote service.
+
+Ambassador is applicable when working with a legacy remote service which cannot be modified or would be extremely 
+difficult to modify. Connectivity features can be implemented on the client avoiding the need for changes on the remote 
+service.
 
 * Ambassador provides a local interface for a remote service.
 * Ambassador provides logging, circuit breaking, retries and security on the client.
@@ -168,10 +193,14 @@ be implemented on the client avoiding the need for changes on the remote service
 * Offload remote service tasks
 * Facilitate network connection
 
-## Real world examples
+## Known uses
 
 * [Kubernetes-native API gateway for microservices](https://github.com/datawire/ambassador)
 
+## Related patterns
+
+* [Proxy](https://java-design-patterns.com/patterns/proxy/)
+
 ## Credits
 
 * [Ambassador pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/ambassador)

ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java

@@ -29,5 +29,5 @@ package com.iluwatar.ambassador;
 interface RemoteServiceInterface {
   int FAILURE = -1;
 
-  long doRemoteFunction(int value) throws Exception;
+  long doRemoteFunction(int value);
 }

proxy/README.md

@@ -132,12 +132,16 @@ are several common situations in which the Proxy pattern is applicable
 
 * [Controlling Access With Proxy Pattern](http://java-design-patterns.com/blog/controlling-access-with-proxy-pattern/)
 
-## Real world examples
+## Known uses
 
 * [java.lang.reflect.Proxy](http://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Proxy.html)
 * [Apache Commons Proxy](https://commons.apache.org/proper/commons-proxy/)
 * Mocking frameworks Mockito, Powermock, EasyMock
 
+## Related patterns
+
+* [Ambassador](https://java-design-patterns.com/patterns/ambassador/)
+
 ## Credits
 
 * [Design Patterns: Elements of Reusable Object-Oriented Software](https://www.amazon.com/gp/product/0201633612/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0201633612&linkCode=as2&tag=javadesignpat-20&linkId=675d49790ce11db99d90bde47f1aeb59)