Merge pull request iluwatar#629 from rastdeepanshu/throttling-pattern

Throttling pattern

Author: iluwatar

pom.xml

@@ -145,7 +145,8 @@
         <module>cqrs</module>
         <module>event-sourcing</module>
         <module>data-transfer-object</module>
-    </modules>
+    <module>throttling</module>
+  </modules>
 
     <dependencyManagement>
         <dependencies>
@@ -488,4 +489,4 @@
         </plugins>
     </reporting>
 
-</project>
+</project>

throttling/README.md

@@ -0,0 +1,20 @@
+---
+layout: pattern
+title: Throttling pattern
+folder: throttling
+permalink: /patterns/throttling/
+tags:
+ - Java
+ - Difficulty-Beginner
+ - Throttling
+---
+
+## Intent
+Ensure that a given client is not able to access service resources more than the assigned limit.
+![alt text](./etc/throttling-patern.png "Throttling pattern")
+
+## Applicability
+The Throttling pattern should be used:
+
+* when a service access needs to be restricted to not have high impacts on the performance of the service.
+* when multiple clients are consuming the same service resources and restriction has to be made according to the usage per client.

throttling/etc/throttling-pattern.png

@@ -0,0 +1,29 @@
+@startuml
+package com.iluwatar.tls {
+  class App {
+    - LOGGER : Logger {static}
+    + App()
+    + main(args : String[]) {static}
+    - makeServiceCalls(service : B2BService) {static}
+  }
+  ~class B2BService {
+    - LOGGER : Logger {static}
+    - callsCounter : int
+    - tenant : Tenant
+    + B2BService(tenant : Tenant)
+    + dummyCustomerApi() : int
+    + getCurrentCallsCount() : int
+    - getRandomCustomerId() : int
+  }
+  class Tenant {
+    - allowedCallsPerSecond : int
+    - name : String
+    + Tenant(name : String, allowedCallsPerSecond : int)
+    + getAllowedCallsPerSecond() : int
+    + getName() : String
+    + setAllowedCallsPerSecond(allowedCallsPerSecond : int)
+    + setName(name : String)
+  }
+}
+B2BService -->  "-tenant" Tenant
+@enduml

throttling/etc/throttling.urm.puml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014 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.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>java-design-patterns</artifactId>
+        <groupId>com.iluwatar</groupId>
+        <version>1.17.0-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>throttling</artifactId>
+	<dependencies>
+		<dependency>
+			<groupId>junit</groupId>
+			<artifactId>junit</artifactId>
+		</dependency>
+	</dependencies>
+
+</project>

throttling/pom.xml

@@ -0,0 +1,90 @@
+/**
+ * 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.throttling;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.iluwatar.throttling.timer.Throttler;
+import com.iluwatar.throttling.timer.ThrottleTimerImpl;
+
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Throttling pattern is a design pattern to throttle or limit the use of resources or even a complete service by
+ * users or a particular tenant. This can allow systems to continue to function and meet service level agreements,
+ * even when an increase in demand places load on resources.
+ * <p>
+ *     In this example we have ({@link App}) as the initiating point of the service.
+ *     This is a time based throttling, i.e. only a certain number of calls are allowed per second.
+ * </p>
+ * ({@link Tenant}) is the Tenant POJO class with which many tenants can be created
+ * ({@link B2BService}) is the service which is consumed by the tenants and is throttled.
+ */
+public class App {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(App.class);
+
+  /**
+   * Application entry point
+   * @param args main arguments
+   */
+  public static void main(String[] args) {
+
+    Tenant adidas = new Tenant("Adidas", 5);
+    Tenant nike = new Tenant("Nike", 6);
+
+    ExecutorService executorService = Executors.newFixedThreadPool(2);
+    
+    executorService.execute(() -> makeServiceCalls(adidas));
+    executorService.execute(() -> makeServiceCalls(nike));
+    
+    executorService.shutdown();
+    try {
+      executorService.awaitTermination(10, TimeUnit.SECONDS);
+    } catch (InterruptedException e) {
+      LOGGER.error("Executor Service terminated: {}", e.getMessage());
+    }
+  }
+
+  /**
+   * Make calls to the B2BService dummy API
+   * @param service an instance of B2BService
+   */
+  private static void makeServiceCalls(Tenant tenant) {
+    Throttler timer = new ThrottleTimerImpl(10);
+    B2BService service = new B2BService(timer);
+    for (int i = 0; i < 20; i++) {
+      service.dummyCustomerApi(tenant);
+//    Sleep is introduced to keep the output in check and easy to view and analyze the results.
+      try {
+        Thread.sleep(1);
+      } catch (InterruptedException e) {
+        LOGGER.error("Thread interrupted: {}", e.getMessage());
+      }
+    }
+  }
+}

throttling/src/main/java/com/iluwatar/throttling/App.java

@@ -0,0 +1,62 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 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.throttling;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.iluwatar.throttling.timer.Throttler;
+
+import java.util.concurrent.ThreadLocalRandom;
+
+/**
+ * A service which accepts a tenant and throttles the resource based on the time given to the tenant.
+ */
+class B2BService {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(B2BService.class);
+
+  public B2BService(Throttler timer) {
+    timer.start();
+  }
+
+  /**
+   *
+   * @return customer id which is randomly generated
+   */
+  public int dummyCustomerApi(Tenant tenant) {
+    String tenantName = tenant.getName();
+    int count = CallsCount.getCount(tenantName);
+    LOGGER.debug("Counter for {} : {} ", tenant.getName(), count);
+    if (count >= tenant.getAllowedCallsPerSecond()) {
+      LOGGER.error("API access per second limit reached for: {}", tenantName);
+      return -1;
+    }
+    CallsCount.incrementCount(tenantName);
+    return getRandomCustomerId();
+  }
+
+  private int getRandomCustomerId() {
+    return ThreadLocalRandom.current().nextInt(1, 10000);
+  }
+}

throttling/src/main/java/com/iluwatar/throttling/B2BService.java

@@ -0,0 +1,72 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 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.throttling;
+
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * A class to keep track of the counter of different Tenants
+ * @author drastogi
+ *
+ */
+public final class CallsCount {
+  private static Map<String, Integer> tenantCallsCount = new ConcurrentHashMap<>();
+
+  /**
+   * Add a new tenant to the map.
+   * @param tenantName name of the tenant.
+   */
+  public static void addTenant(String tenantName) {
+    if (!tenantCallsCount.containsKey(tenantName)) {
+      tenantCallsCount.put(tenantName, 0);
+    }
+  }
+  
+  /**
+   * Increment the count of the specified tenant.
+   * @param tenantName name of the tenant.
+   */
+  public static void incrementCount(String tenantName) {
+    tenantCallsCount.put(tenantName, tenantCallsCount.get(tenantName) + 1);
+  }
+  
+  /**
+   * 
+   * @param tenantName name of the tenant.
+   * @return the count of the tenant.
+   */
+  public static int getCount(String tenantName) {
+    return tenantCallsCount.get(tenantName);
+  }
+  
+  /**
+   * Resets the count of all the tenants in the map.
+   */
+  public static void reset() {
+    for (Entry<String, Integer> e : tenantCallsCount.entrySet()) {
+      tenantCallsCount.put(e.getKey(), 0);
+    }
+  }
+}

throttling/src/main/java/com/iluwatar/throttling/CallsCount.java

@@ -0,0 +1,57 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 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.throttling;
+
+import java.security.InvalidParameterException;
+
+/**
+ * A Pojo class to create a basic Tenant with the allowed calls per second.
+ */
+public class Tenant {
+
+  private String name;
+  private int allowedCallsPerSecond;
+
+  /**
+   *
+   * @param name Name of the tenant
+   * @param allowedCallsPerSecond The number of calls allowed for a particular tenant.
+   * @throws InvalidParameterException If number of calls is less than 0, throws exception.
+   */
+  public Tenant(String name, int allowedCallsPerSecond) {
+    if (allowedCallsPerSecond < 0) {
+      throw new InvalidParameterException("Number of calls less than 0 not allowed");
+    }
+    this.name = name;
+    this.allowedCallsPerSecond = allowedCallsPerSecond;
+    CallsCount.addTenant(name);
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public int getAllowedCallsPerSecond() {
+    return allowedCallsPerSecond;
+  }
+}