Merge pull request #9 from DavidTheExplorer/1.4.0

v1.4.0 - Breaking Changes, JavaDocs, and critical bug fixes.

Author: DavidTheExplorer

README.md

@@ -1,25 +1,26 @@
 # Tzeva Adom API
-Async Java API that listens to `Pikud Ha'oref API` and notifies registered listeners as soon as a Tzeva Adom happens.
+Async Java API that listens to `Pikud Ha'oref` and notifies registered listeners as soon as a Tzeva Adom happens.
 
 
 ## How to use
 Let's create a notifier that logs a message when it's Tzeva Adom:
 ```java
 TzevaAdomNotifier
-        .requestFromPikudHaoref()
+        .basedOnPikudHaoref()
         .every(Duration.ofSeconds(3)) //amount of delay between requests
         .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(); //async
 ```
 
-You can save the notifier object by calling `build()` instead of `listen()`, in order to add functionality or get data from it:
+You can save the notifier object by calling `build()` instead of `listen()` in order to add functionality or get data:
 ```java
-TzevaAdomNotifier notifier = TzevaAdomNotifier
-        // builder pattern goes here
+TzevaAdomNotifier notifier = new TzevaAdomNotifier.Builder()
+        // the rest of the builder pattern
         .build();
-        
-notifier.listen();
+
+// later  
+Alert lastAlert = notifier.getLastAlert();
 ```
 
 Add more listeners anytime:
@@ -30,13 +31,12 @@ notifier.addListener(alert -> ...);
 Retrieve the Tzeva Adom alerts encountered while running:
 ```java
 //run the notifier async and sleep for a day
-notifier.run();
+notifier.listen();
 TimeUnit.DAYS.sleep(1);
 
 LOGGER.info("There were {} alerts in the last 24 hours:", notifier.getHistory().size());
 
-//Pro Tip: TzevaAdomNotifier implements Iterable!
-for(Alert alert : notifier) 
+for(Alert alert : notifier.getHistory()) 
 {
         LOGGER.info("Alert in {} at {}", alert.getCity(), alert.getDate());
 }
@@ -55,7 +55,7 @@ Maven Repository:
 <dependency>
         <groupId>com.github.DavidTheExplorer</groupId>
         <artifactId>Tzeva-Adom-API</artifactId>
-        <version>1.1.0</version>
+        <version>1.4.0</version>
 </dependency>
 ```
 
@@ -67,4 +67,3 @@ Either implement `AlertSource` or extend `JSONAlertSource` for JSON APIs, and th
 ```java
 new TzevaAdomNotifier.Builder()
 .requestFrom(new YourAlertSource())
-.listen();

pom.xml

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

src/main/java/dte/tzevaadomapi/alert/Alert.java

@@ -3,6 +3,9 @@
 import java.time.LocalDateTime;
 import java.util.Objects;
 
+/**
+ * Represents a <b>Tzeva Adom</b> alert and contains information about where/when it happened.
+ */
 public class Alert
 {
 	private final String city;

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

@@ -2,11 +2,26 @@
 
 import dte.tzevaadomapi.alert.Alert;
 
+/**
+ * Responsible of gathering information about the most recent {@link Alert Tzeva Adom} in Israel.
+ */
 @FunctionalInterface
 public interface AlertSource
 {
+	/**
+	 * Returns an updated {@link Alert} that describes the last <b>Tzeva Adom</b> in Israel.
+	 * 
+	 * @return The last alert that happened in Israel.
+	 * @throws Exception If the information gathering process encountered an exception(typically {@code IOException})
+	 * @apiNote This should never return a cached value, don't make a joke.
+	 */
 	Alert getMostRecentAlert() throws Exception;
 
 
-	public static final Alert EMPTY_RESPONSE = null;
+	/**
+	 * This object signals that no Exception occurred while {@link #getMostRecentAlert()}, but no alert was returned.
+	 * <p>
+	 * Example: <i>Pikud Ha'oref</i> usually returns an empty JSON if no Tzeva Adom happened in the last 24 hours.
+	 */
+	Alert NO_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())
-			return EMPTY_RESPONSE;
+			return NO_RESPONSE;
 
 		return fromJSON((JSONObject) alertsJsonArray.get(0));
 	}

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

@@ -2,6 +2,9 @@
 
 import dte.tzevaadomapi.alert.Alert;
 
+/**
+ * Represents an action that should be done <b>immediately</b> when a Tzeva Adom takes place.
+ */
 @FunctionalInterface
 public interface TzevaAdomListener
 {

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

@@ -16,10 +16,14 @@
 import dte.tzevaadomapi.alertsource.PHOAlertSource;
 
 /**
- * Notifies registered listeners once a Tzeva Adom takes place.
+ * Notifies registered listeners once a <b>Tzeva Adom</b> takes place.
  * <p>
- * A request for the most recent alert is sent every constant duration, and the result is then compared to the previous one.
- * If the 2 alerts don't equal - It's <b>Tzeva Adom</b> and the registered listeners are notified.
+ * The workflow of the notifier is:
+ * <ol>
+ * 	<li> Request the most recent alert sent every constant duration(typically ~2 seconds)
+ * 	<li> Compare it to the previous one, or store the first result:
+ * 	<li> If the 2 alerts are not identical, It's <b>Tzeva Adom</b> - and the listeners are notified immediately.
+ * </ol>
  */
 public class TzevaAdomNotifier
 {
@@ -36,12 +40,18 @@ private TzevaAdomNotifier(AlertSource alertSource, Duration requestDelay, Consum
 		this.requestFailureHandler = requestFailureHandler;
 	}
 
-	public static Builder requestFromPikudHaoref() 
+	public static Builder basedOnPikudHaoref() 
 	{
 		return new Builder()
 				.requestFrom(new PHOAlertSource());
 	}
 
+	/**
+	 * Starts listening and reacting to <b>Tzeva Adom</b> on a separate Thread, 
+	 * and returns the the corresponding {@link CompletableFuture} object for further control.
+	 * 
+	 * @return The {@link CompletableFuture} responsible of reacting to <b>Tzeva Adoms</b>.
+	 */
 	public CompletableFuture<Void> listen()
 	{
 		return CompletableFuture.runAsync(() -> 
@@ -54,11 +64,11 @@ public CompletableFuture<Void> listen()
 				Alert alert = getMostRecentAlert();
 
 				//ignore empty responses
-				if(alert == AlertSource.EMPTY_RESPONSE)
+				if(alert == AlertSource.NO_RESPONSE)
 					continue;
 
 				//if the last alert in history equals the the last requested - it's not Tzeva Adom
-				if(lastTzevaAdom.equals(alert)) 
+				if(alert.equals(lastTzevaAdom)) 
 					continue;
 
 				lastTzevaAdom = alert;

src/test/java/dte/tzevaadomapi/notifier/TzevaAdomNotifierTest.java

@@ -6,6 +6,7 @@
 import java.time.Duration;
 import java.time.LocalDateTime;
 
+import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -53,6 +54,20 @@ public void testConsecutiveTzevaAdom() throws Exception
 		assertEquals(3, simulateNotifier(4).getHistory().size());
 	}
 
+	@Test
+	@DisplayName("The usual request flow where 99% are no responses")
+	public void testUsualRoutine() throws Exception 
+	{
+		when(this.alertSource.getMostRecentAlert()).thenReturn(
+				AlertSource.NO_RESPONSE,
+				AlertSource.NO_RESPONSE, 
+				AlertSource.NO_RESPONSE, 
+				AlertSource.NO_RESPONSE,  
+				createAlert("Tel Aviv"));
+		
+		assertEquals(1, simulateNotifier(5).getHistory().size());
+	}
+	
 	private static Alert createAlert(String city) 
 	{
 		return new Alert(city, "חדירת מחבלים", LocalDateTime.now());
@@ -69,7 +84,6 @@ private TzevaAdomNotifier simulateNotifier(int alertsAmount) throws InterruptedE
 		TzevaAdomNotifier notifier = new TzevaAdomNotifier.Builder()
 				.every(Duration.ofMillis(5))
 				.requestFrom(this.alertSource)
-				.onFailedRequest(Exception::printStackTrace)
 				.build();
 
 		notifier.listen();