Merge pull request #15 from DavidTheExplorer/1.7.2

v1.7.2

Author: DavidTheExplorer

README.md

@@ -60,17 +60,25 @@ Maven Repository:
 
 
 ## Adjustments
-Everything in the library is customizable.
--  If the endpoint of Pikud Ha'oref was changed or your alerts come from somewhere else:\
-   Implement `AlertSource` and then create your notifier like this:
-   
+- Override the frequency of Tzeva Adom checks:
+  ```java
+  new TzevaAdomNotifier.Builder()
+  	.requestEvery(Duration.ofSeconds(3))
+  ```
+  
+-  Change the endpoint of Pikud Ha'oref if it was changed:
    ```java
+   //PHOAlertSource is the default AlertSource implementation, you can also implement your own.
+   PHOAlertSource alertSource = new PHOAlertSource();
+   alertSource.changeRequestURL(new URL("..."));
+   
    new TzevaAdomNotifier.Builder()
-   	.requestFrom(new YourAlertSource())
+   	.requestFrom(alertSource)
    ```
-- Override the frequency of the Tzeva Adom checks:
- 
+   
+- Prevent console spam when handling exceptions:
   ```java
+  //LimitedExceptionHandler is a wrapper of Consumer<Exception> that stops handling after X times
   new TzevaAdomNotifier.Builder()
-  	.requestEvery(Duration.ofSeconds(3))
-  ```
+  	.onFailedRequest(new LimitedExceptionHandler(3, yourExceptionHandler));
+   ```

pom.xml

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

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

@@ -10,9 +10,9 @@
 public interface AlertSource
 {
 	/**
-	 * Returns the most recent {@link Alert} that happened in Israel.
+	 * Returns the most recent {@link Alert} that happened in Israel
 	 * 
-	 * @return Either the alert, or {@link #NO_RESULT} if one wasn't found.
+	 * @return The alert, or null if no info was found.
 	 * @throws Exception If an exception happened while gathering the alert.
 	 */
 	Alert getMostRecentAlert() throws Exception;
@@ -21,16 +21,8 @@ public interface AlertSource
 	 * Returns all the alerts that happened since the provided {@code alert}.
 	 * 
 	 * @param alert The 'minimum' alert.
-	 * @return The alerts list, or an empty result if there was no Tzeva Adom afterwards.
-	 * @throws Exception iF an exception happened while gathering the alerts.
+	 * @return The alerts list, or an empty result if there was no Tzeva Adom afterward.
+	 * @throws Exception If an exception happened while gathering the alerts.
 	 */
 	Deque<Alert> getSince(Alert alert) throws Exception;
-	
-	
-	/**
-	 * This object signals when {@link #getMostRecentAlert()} couldn't find an alert to return, and no exceptions occurred.
-	 * <p>
-	 * This is addressed because <i>Pikud Ha'oref</i> returns an empty JSON if no Tzeva Adom happened in the last 24 hours.
-	 */
-	Alert NO_RESULT = null;
 }

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

@@ -15,7 +15,7 @@
  */
 public abstract class OnlineAlertSource implements AlertSource
 {
-	private final URL requestURL;
+	private URL requestURL;
 	private final Proxy proxy;
 
 	public OnlineAlertSource(URL requestURL)
@@ -28,6 +28,11 @@ public OnlineAlertSource(URL requestURL, Proxy proxy)
 		this.requestURL = requestURL;
 		this.proxy = proxy;
 	}
+
+	public void changeRequestURL(URL requestURL)
+	{
+		this.requestURL = requestURL;
+	}
 
 	protected URLConnection openConnection() throws IOException 
 	{

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

@@ -1,5 +1,6 @@
 package dte.tzevaadomapi.alertsource;
 
+import java.io.IOException;
 import java.lang.reflect.Type;
 import java.net.Proxy;
 import java.net.URL;
@@ -17,7 +18,7 @@
 
 import dte.tzevaadomapi.alert.Alert;
 import dte.tzevaadomapi.utils.URLFactory;
-import dte.tzevaadomapi.utils.UncheckedExceptions.CheckedFunction;
+import dte.tzevaadomapi.utils.CheckedFunction;
 
 /**
  * Requests Alerts from Pikud Ha'Oref.
@@ -79,12 +80,19 @@ public Deque<Alert> getSince(Alert alert) throws Exception
 		});
 	}
 
-	//starts reading the JSON list posted by Pikud Ha'oref, and applies the function on it
-	private <T> T beginReadingArray(CheckedFunction<JsonReader, T> resultParser) 
+	//starts reading the JSON array posted by Pikud Ha'oref, and applies the function on it
+	private <T> T beginReadingArray(CheckedFunction<JsonReader, T> resultParser)
 	{
 		try(JsonReader reader = new JsonReader(newInputStreamReader()))
 		{
-			reader.beginArray();
+			try
+			{
+				reader.beginArray();
+			}
+			catch(IOException exception)
+			{
+				return null;
+			}
 
 			return resultParser.apply(reader);
 		}

src/main/java/dte/tzevaadomapi/exceptionhandler/LimitedExceptionHandler.java

@@ -0,0 +1,43 @@
+package dte.tzevaadomapi.exceptionhandler;
+
+import dte.tzevaadomapi.alert.Alert;
+import dte.tzevaadomapi.listener.TzevaAdomListener;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.function.Consumer;
+
+/**
+ * An implementation of {@link Consumer<Exception>} that handles a predetermined amount of exceptions, and then stops until the next Tzeva Adom;
+ * This prevents unwanted behaviour such as logging the same exception endlessly(e.g. when the <i>AlertSource</i>'s server is offline).
+ *
+ * @implSpec To prevent swallowing 2 different exceptions, the limit is applied per <i>Exception Class</i> -
+ * So for a limit of 5, only 5 <i>NullPointerException</i>s and 5 <i>IOException</i>s would be handled.
+ */
+public class LimitedExceptionHandler implements Consumer<Exception>, TzevaAdomListener
+{
+    private final Consumer<Exception> delegate;
+    private final int limit;
+    private final Map<Class<?>, Integer> timesHandled = new HashMap<>();
+
+    public LimitedExceptionHandler(int limit, Consumer<Exception> delegate)
+    {
+        this.delegate = delegate;
+        this.limit = limit;
+    }
+
+    @Override
+    public void accept(Exception exception)
+    {
+        this.timesHandled.merge(exception.getClass(), 1, Integer::sum);
+
+        if(this.timesHandled.get(exception.getClass()) <= this.limit)
+            this.delegate.accept(exception);
+    }
+
+    @Override
+    public void onTzevaAdom(Alert alert)
+    {
+        this.timesHandled.clear();
+    }
+}

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

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

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

@@ -26,7 +26,7 @@ void update(Collection<Alert> alerts)
 	}
 
 	/**
-	 * Returns the most recent alert in the history of the underlying notifier.
+	 * Returns the most recent alert in this history.
 	 * 
 	 * @return The most recent alert.
 	 */
@@ -36,10 +36,12 @@ public Optional<Alert> getMostRecent()
 	}
 
 	/**
-	 * Returns the list of alerts that happened in a provided {@code region} since the underlying notifier was started.
+	 * Returns the list of alerts that happened in a provided {@code region}.
 	 * 
 	 * @param region The region, may be partial.
 	 * @return The region's history.
+	 *
+	 * @implSpec This method accepts partial regions - So if "תל" is provided, the result would contain alerts from both <i>תל אביב</i> and <i>תל מונד</i>.
 	 */
 	public List<Alert> ofRegion(String region)
 	{
@@ -49,7 +51,7 @@ public List<Alert> ofRegion(String region)
 	}
 
 	/**
-	 * Returns a {@link Deque} representation of this history.
+	 * Returns a {@link Deque} snapshot of this history.
 	 * 
 	 * @return The deque.
 	 */
@@ -59,7 +61,7 @@ public Deque<Alert> toDeque()
 	}
 
 	/**
-	 * Returns how many alerts were recorded since the underlying notifier was started.
+	 * Returns how many alerts this history contains.
 	 * 
 	 * @return This history's size.
 	 */

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

@@ -12,11 +12,12 @@
 import dte.tzevaadomapi.alert.Alert;
 import dte.tzevaadomapi.alertsource.AlertSource;
 import dte.tzevaadomapi.alertsource.PHOAlertSource;
+import dte.tzevaadomapi.exceptionhandler.LimitedExceptionHandler;
 import dte.tzevaadomapi.listener.TzevaAdomListener;
-import dte.tzevaadomapi.utils.UncheckedExceptions.CheckedSupplier;
+import dte.tzevaadomapi.utils.CheckedFunction;
 
 /**
- * Notifies registered listeners immediately once a <b>Tzeva Adom</b> takes place.
+ * Notifies registered listeners immediately upon a <b>Tzeva Adom</b>.
  */
 public class TzevaAdomNotifier
 {
@@ -25,6 +26,7 @@ public class TzevaAdomNotifier
 	private final Consumer<Exception> requestFailureHandler;
 	private final Collection<TzevaAdomListener> listeners;
 	private final TzevaAdomHistory history = new TzevaAdomHistory();
+	
 	private Alert mostRecentAlert; //only used in listenAsync(), holding it here solves the effectively final problem
 
 	private TzevaAdomNotifier(Collection<TzevaAdomListener> listeners, AlertSource alertSource, Duration requestDelay, Consumer<Exception> requestFailureHandler)
@@ -36,7 +38,7 @@ private TzevaAdomNotifier(Collection<TzevaAdomListener> listeners, AlertSource a
 	}
 
 	/**
-	 * Starts listening to incoming alerts, and returns the corresponding {@link CompletableFuture} object for further control.
+	 * Starts listening to alerts, and returns the corresponding {@link CompletableFuture} object for further control.
 	 * <p>
 	 * In order to implement a program whose sole workflow is to be idle until there is an alert, call {@link CompletableFuture#join() join()} on the result.
 	 * 
@@ -47,13 +49,13 @@ public CompletableFuture<Void> listenAsync()
 		return CompletableFuture.runAsync(() -> 
 		{
 			//start with the most recent alert
-			this.mostRecentAlert = requestMostRecentAlert();
+			this.mostRecentAlert = requestFromSource(AlertSource::getMostRecentAlert);
 
 			while(true)	
 			{
-				Deque<Alert> newAlerts = requestFromSource(() -> this.alertSource.getSince(this.mostRecentAlert));
-				
-				//if there are no new alerts - it's not Tzeva Adom
+				Deque<Alert> newAlerts = requestFromSource(source -> source.getSince(this.mostRecentAlert));
+
+				//wait until a terror organization decides to launch rockets
 				if(newAlerts.isEmpty()) 
 					continue;
 
@@ -68,7 +70,7 @@ public CompletableFuture<Void> listenAsync()
 	}
 
 	/**
-	 * Adds a listener to notify when it's Tzeva Adom.
+	 * Adds a listener to notify upon a Tzeva Adom.
 	 * 
 	 * @param listener The listener.
 	 */
@@ -80,37 +82,28 @@ public void addListener(TzevaAdomListener listener)
 	/**
 	 * Returns the captured history since {@link #listenAsync()} was called.
 	 * 
-	 * @return The tzeva adom history.
+	 * @return The Tzeva Adom history.
 	 */
 	public TzevaAdomHistory getHistory()
 	{
 		return this.history;
 	}
-	
-	private Alert requestMostRecentAlert() 
-	{
-		Alert alert;
-		
-		//wait until Hamas decides to launch rockets
-		do 
-		{
-			alert = requestFromSource(this.alertSource::getMostRecentAlert);
-		}
-		while(alert == AlertSource.NO_RESULT);
-		
-		return alert;
-	}
 
-	private <T> T requestFromSource(CheckedSupplier<T> resultFactory)
+	private <T> T requestFromSource(CheckedFunction<AlertSource, T> request)
 	{
 		while(true)
 		{
 			try 
 			{
 				//sleep the defined delay
 				TimeUnit.MILLISECONDS.sleep(this.requestDelay.toMillis());
-				
-				return resultFactory.get();
+
+				T result = request.apply(this.alertSource);
+
+				if(result == null)
+					continue;
+
+				return result;
 			}
 			catch(Exception exception) 
 			{
@@ -146,6 +139,14 @@ public Builder requestEvery(Duration requestDelay)
 			return this;
 		}
 
+		/**
+		 * Determines how to handle exceptions when alerts are fetched.
+		 *
+		 * @apiNote To prevent unwanted behaviour such as logging the same IOException when the server is offline, You can pass a {@link LimitedExceptionHandler}.
+		 *
+		 * @param handler The exception handler.
+		 * @return The same instance.
+		 */
 		public Builder onFailedRequest(Consumer<Exception> handler) 
 		{
 			this.requestFailureHandler = handler;
@@ -174,6 +175,10 @@ public TzevaAdomNotifier build()
 			if(this.listeners.isEmpty())
 				throw new IllegalStateException("At least one listener must be provided to create a TzevaAdomNotifier.");
 
+			//support for LimitedExceptionHandler
+			if(this.requestFailureHandler instanceof TzevaAdomListener)
+				this.listeners.add((TzevaAdomListener) this.requestFailureHandler);
+
 			return new TzevaAdomNotifier(this.listeners, this.alertSource, this.requestDelay, this.requestFailureHandler);
 		}
 	}

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

@@ -0,0 +1,7 @@
+package dte.tzevaadomapi.utils;
+
+@FunctionalInterface
+public interface CheckedFunction<T, R>
+{
+    R apply(T object) throws Exception;
+}