Merge pull request #6 from DavidTheExplorer/1.2.0

v1.2.0 - CompletableFuture Support

Author: DavidTheExplorer

README.md

@@ -1,19 +1,19 @@
 # Tzeva Adom API
-Simple Java API that listens to `Pikud Haoref's API` and notifies registered listeners once a Tzeva Adom takes place.
+Async Java API that listens to `Pikud Ha'oref API` and notifies registered listeners as soon as a Tzeva Adom happens.
 
 
 ## How to use
-Let's create a notifier object that logs a message when it's Tzeva Adom:
+Let's create a notifier that logs a message when it's Tzeva Adom:
 ```java
 TzevaAdomNotifier
         .requestFromPikudHaoref()
         .every(Duration.ofSeconds(3)) //amount of delay between requests
-        .onFailedRequest(exception -> LOGGER.error("Failed to send a request to Pikud Ha'oref...", exception))
+        .onFailedRequest(exception -> LOGGER.error("Failed to request the last alert from Pikud Ha'oref", exception))
         .onTzevaAdom(alert -> LOGGER.info("Tzeva Adom at: " + alert.getCity()))
-        .listen();
+        .listen(); //async
 ```
 
-You can save the notifier object in order to add functionality or get data from it, by calling `build()` instead of `listen()`:
+You can save the notifier object by calling `build()` instead of `listen()`, in order to add functionality or get data from it:
 ```java
 TzevaAdomNotifier notifier = TzevaAdomNotifier
         // builder pattern goes here
@@ -22,14 +22,17 @@ TzevaAdomNotifier notifier = TzevaAdomNotifier
 notifier.listen();
 ```
 
-Adding Listeners anytime:
+Add more listeners anytime:
 ```java
 notifier.addListener(alert -> ...);
 ```
 
-Retrieving the Tzeva Adom Alerts encountered while running:
+Retrieve the Tzeva Adom alerts encountered while running:
 ```java
+//run the notifier async and sleep for a day
+notifier.run();
 TimeUnit.DAYS.sleep(1);
+
 LOGGER.info("There were {} alerts in the last 24 hours:", notifier.getHistory().size());
 
 //Pro Tip: TzevaAdomNotifier implements Iterable!

pom.xml

@@ -4,7 +4,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>dte</groupId>
 	<artifactId>tzevaadomapi</artifactId>
-	<version>1.1.0</version>
+	<version>1.2.0</version>
 
 	<build>
 		<plugins>

src/main/java/dte/tzevaadomapi/alertsource/AlertSource.java

@@ -6,4 +6,7 @@
 public interface AlertSource
 {
 	Alert getMostRecentAlert() throws Exception;
+	
+	
+	public static final Alert EMPTY_RESPONSE = null;
 }

src/main/java/dte/tzevaadomapi/alertsource/json/JSONAlertSource.java

@@ -31,7 +31,7 @@ public Alert getMostRecentAlert() throws Exception
 		JSONArray alertsJsonArray = requestAlertsJSON();
 
 		if(alertsJsonArray == null || alertsJsonArray.isEmpty())
-			throw new IllegalArgumentException("Cannot get the most recent alert due to an empty JSON response!");
+			return EMPTY_RESPONSE;
 
 		return fromJSON((JSONObject) alertsJsonArray.get(0));
 	}

src/main/java/dte/tzevaadomapi/notifier/TzevaAdomNotifier.java

@@ -8,6 +8,7 @@
 import java.util.LinkedList;
 import java.util.Objects;
 import java.util.Set;
+import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Consumer;
 
@@ -44,24 +45,31 @@ public static Builder requestFromPikudHaoref()
 				.requestFrom(new PHOAlertSource());
 	}
 
-	public void listen() throws InterruptedException
+	public CompletableFuture<Void> listen()
 	{
-		//start with an initial alert - against which future alerts will be compared
-		Alert lastTzevaAdom = getMostRecentAlert();
-
-		while(true)
+		return CompletableFuture.runAsync(() -> 
 		{
-			Alert alert = getMostRecentAlert();
-			
-			//if the last alert in history doesn't equal to the last requested one - It's TZEVA ADOM
-			if(lastTzevaAdom.equals(alert)) 
-				continue;
-			
-			lastTzevaAdom = alert;
-			
-			this.listeners.forEach(listener -> listener.accept(alert));
-			this.history.add(alert);
-		}
+			//start with an initial alert - against which future alerts will be compared
+			Alert lastTzevaAdom = getMostRecentAlert();
+
+			while(true)
+			{
+				Alert alert = getMostRecentAlert();
+				
+				//ignore empty responses
+				if(alert == AlertSource.EMPTY_RESPONSE)
+					continue;
+				
+				//if the last alert in history equals the the last requested - it's not Tzeva Adom
+				if(lastTzevaAdom.equals(alert)) 
+					continue;
+				
+				lastTzevaAdom = alert;
+				
+				this.listeners.forEach(listener -> listener.accept(alert));
+				this.history.add(alert);
+			}
+		});
 	}
 
 	public void addListener(Consumer<Alert> tzevaAdomListener) 
@@ -85,14 +93,14 @@ public Iterator<Alert> iterator()
 		return this.history.iterator();
 	}
 
-	private Alert getMostRecentAlert() throws InterruptedException
+	private Alert getMostRecentAlert()
 	{
 		while(true)
 		{
-			TimeUnit.MILLISECONDS.sleep(this.requestDelay.toMillis());
-				
 			try
 			{
+				TimeUnit.MILLISECONDS.sleep(this.requestDelay.toMillis());
+				
 				return this.alertSource.getMostRecentAlert();
 			}
 			catch(Exception exception)
@@ -135,9 +143,9 @@ public Builder onTzevaAdom(Consumer<Alert> listener)
 			return this;
 		}
 
-		public void listen() throws InterruptedException
+		public CompletableFuture<Void> listen()
 		{
-			build().listen();
+			return build().listen();
 		}
 
 		public TzevaAdomNotifier build()

src/main/java/dte/tzevaadomapi/utils/UncheckedExceptions.java

@@ -1,12 +1,10 @@
 package dte.tzevaadomapi.notifier;
 
-import static dte.tzevaadomapi.utils.UncheckedExceptions.unchecked;
 import static org.junit.Assert.assertEquals;
 import static org.mockito.Mockito.when;
 
 import java.time.Duration;
 import java.time.LocalDateTime;
-import java.util.concurrent.CompletableFuture;
 
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestInstance;
@@ -74,7 +72,7 @@ private TzevaAdomNotifier simulateNotifier(int alertsAmount) throws InterruptedE
 				.onFailedRequest(Exception::printStackTrace)
 				.build();
 
-		CompletableFuture.runAsync(unchecked(notifier::listen));
+		notifier.listen();
 
 		//because I'm ahla gever, every alert gets 10ms to be recorded
 		Thread.sleep(Duration.ofMillis(alertsAmount * 10).toMillis());